Metadata-Version: 2.2
Name: sympt
Version: 1.2.1
Summary: A solver for perturbative expansions in quantum systems
Author-email: Monica Benito <monica.benito@uni-a.de>, Giovanni Francesco Diotallevi <francesco.diotallevi@uni-a.de>, Irving Leander Reascos Valencia <irving.reascos.valencia@uni-a.de>
License: MIT License
        
        Copyright (c) 2024 QCode
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Repository, https://github.com/qcode-uni-a/sympt
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ipython==8.20
Requires-Dist: multimethod==1.12
Requires-Dist: numpy==2.0
Requires-Dist: sympy==1.13.3
Requires-Dist: tabulate==0.9
Requires-Dist: tqdm==4.66
Requires-Dist: colorama

# SymPT: Symbolic Perturbation Theory Toolbox

Welcome to **SymPT**, a Python package designed for performing symbolic perturbative transformations on quantum systems. SymPT leverages the **Schrieffer-Wolff Transformation (SWT)** and other related techniques to compute effective Hamiltonians in a systematic and efficient manner. The library offers a suite of tools for block-diagonalization, full-diagonalization, and custom transformations, supporting both time-independent and time-dependent systems.

This document provides comprehensive guidance on using SymPT, detailing its key features, algorithms, and implementation. Detailed documentation can be found [here](https://qcode-uni-a.github.io/sympt/). 

---

## Table of Contents

1. [Overview](#overview)
2. [Key Features](#key-features)
3. [Installation](#installation)
4. [Usage](#usage)
   - [Basic Workflow](#basic-workflow)
   - [Examples](#examples)
5. [Core Classes](#core-classes)
   - [RDSymbol](#rdsymbol)
   - [RDBasis](#rdbasis)
   - [EffectiveFrame](#effectiveframe)
   - [Block](#block)
6. [Algorithms](#algorithms)
   - [Schrieffer-Wolff Transformation (SWT)](#schrieffer-wolff-transformation-swt)
   - [Full-Diagonalization (FD)](#full-diagonalization-fd)
   - [Arbitrary Coupling Elimination (ACE)](#arbitrary-coupling-elimination-ace)
7. [Advanced Tools](#advanced-tools)
8. [Contributing](#contributing)
9. [License](#license)

---

## Overview

SymPT is a symbolic perturbative transformation tool built to help researchers and engineers study quantum systems experiencing perturbative interactions. It computes effective Hamiltonians and performs other transformations using techniques based on SWT, FD, and ACE. The package also supports multi-block diagonalizations, with special emphasis on least-action methods.

---

## Key Features

- **Multiple Transformation Methods**: Includes routines for SWT, FD, ACE.
- **Symbolic Computation**: Powered by `sympy`, enabling exact symbolic results for quantum systems.
- **Customizable Input**: Define Hamiltonians and operators with ease using symbolic expressions.
- **Flexible Output**: Obtain results in operator, matrix, or dictionary forms.
- **Efficient Algorithms**: Leverages caching and optimized partitioning for nested commutator calculations.

---

## Installation

### From PyPI
Make sure to install SymPT on a new python environment. To do so, you can use the Anaconda distribution platform
```bash
conda create -n sympt python
```

SymPT is available on PyPI for easy installation:

```bash
conda activate sympt
pip install sympt
```

### From Source
To install SymPT from the source code, clone the repository and install dependencies:

```bash
git clone https://github.com/qcode-uni-a/sympt.git
cd SymPT
conda activate sympt
pip install .
```

SymPT depends on Python 3.8+ and the following libraries:
- `sympy`: For symbolic computations.
- `numpy`: For matrix operations.
- (Optional) `matplotlib`: For visualizing results.

---

## Usage

### Basic Workflow

1. **Define Symbols and Basis**: Use `RDSymbol` and `RDBasis` to construct system components.
2. **Set Up EffectiveFrame**: Initialize the transformation frame with the Hamiltonian.
3. **Solve the Transformation**: Specify the perturbation order and method (`SWT`, `FD`, or `ACE`).
4. **Extract Results**: Retrieve the effective Hamiltonian or rotate operators into the new frame.

---

### Examples
Here we include two example cases of how to use SymPT. Find more within the Examples folder of this project.
#### Example 1: Schrieffer-Wolff Transformation (SWT)

```python
from sympt import RDSymbol, RDBasis, EffectiveFrame

# Define symbols
omega = RDSymbol('omega', real=True, positive=True)
g = RDSymbol('g', order=1, real=True)

# Define basis and Hamiltonian
spin = RDBasis(name='sigma', dim=2)
s0, sx, sy, sz = spin.basis

H = omega * sz
V = g * sx

# Setup EffectiveFrame
eff_frame = EffectiveFrame(H, V, subspaces=[spin])
eff_frame.solve(max_order=2, method="SW")
H_eff = eff_frame.get_H(return_form="operator")
display(H_eff)
```

#### Example 2: Arbitrary Coupling Elimination (ACE)

```python
from sympt import *
from sympy import Rational

# Define symbols
omega = RDSymbol('omega', order=0, real=True)
omega_z = RDSymbol('omega_z', order=0, real=True)
g = RDSymbol('g', order=1, real=True)

# Define basis and operators
spin = RDBasis(name='sigma', dim=2)
s0, sx, sy, sz = spin.basis
a = BosonOp('a')
ad = Dagger(a)

# Define Hamiltonian
H = omega * ad * a +  Rational(1,2) * omega_z * sz + g * sx * (a + ad)
mask = Block(fin = sx, inf = a, subspaces=[spin]) # this mask is equivalent to "SW" up to second order

# Solve ACE transformation
eff_frame = EffectiveFrame(H, subspaces=[spin])
eff_frame.solve(max_order=2, method="ACE", mask=mask)
H_eff = eff_frame.get_H(return_form="operator")
display(H_eff)
```

---

## Core Classes

### RDSymbol

- Represents scalar, commutative quantities with perturbative orders.
- Example: `omega = RDSymbol('omega', order=0, real=True)`

### RDBasis

- Encodes finite-dimensional subspaces and generates basis operators (e.g., Pauli or Gell-Mann matrices).
- Example: `spin = RDBasis(name='sigma', dim=2)`

### EffectiveFrame

- Central class for setting up and solving perturbative transformations.
- Methods:
  - `.solve()`: Perform the transformation.
  - `.get_H()`: Retrieve the effective Hamiltonian.
  - `.rotate()`: Rotate operators into the new frame.

### Block

- Used in ACE transformations to specify couplings to eliminate.
- Example: `mask = Block(fin=a)`

---

## Algorithms

### Schrieffer-Wolff Transformation (SWT)

Systematically block-diagonalizes the Hamiltonian, focusing on separating diagonal and off-diagonal terms.

### Full-Diagonalization (FD)

Fully diagonalizes the Hamiltonian, eliminating all off-diagonal elements.

### Arbitrary Coupling Elimination (ACE)

Targets specific off-diagonal couplings for elimination, allowing flexible transformations.

---

## Advanced Tools

- **`display_dict`**: Enhanced dictionary printing for Hamiltonians.
- **`group_by_operators`**: Groups terms by their operator components.
- **`get_block_mask`**: Simplifies block-off diagonal mask creation.

---

## Contributing

We welcome contributions! Please:
1. Fork the repository.
2. Create a feature branch.
3. Submit a pull request with detailed descriptions.

---

## License

SymPT is licensed under the MIT License. See `LICENSE` for details.
