You can deploy this model and start earning money today!

raj-dahya/
choi-cholesky

Name: choi-cholesky
Availability: InStock

Cholesky decomposition

2603.19444

10.57967/hf/8114

cc-by-sa-4.0

Views

No views yet

Python version: 3.14

Algorithms for decomposition of CPTP-maps

This code base contains implementations of the algorithm in the paper The Choi-Cholesky algorithm for completely positive maps, in order to empirically verify the correctness of the Choi–Cholesky decomposition of CP- (resp. CPTP-) maps, $\Phi$. Numerical verification occurs by:

Randomly generating a large number of CP- (resp. CPTP-) maps $\Phi$ dually represented by their Choi-matrices $C_{\Phi}$;
Computing the decompositions (the main algorithm)

$$ C_{\Phi} \overset{!}{=} L^{(\Phi)} : (L^{(\Phi)})^{\ast} $$
Verifying that the relative difference

$$ \frac{ | L^{(\Phi)} : (L^{(\Phi)})^{\ast} - C_{\Phi} | }{ | C_{\Phi} | } $$

between the recovered Choi-matrices and the original is below a given tolerance.

References

This code base can be cited¹ as

@misc{Dahya2026RepoChoiCholesky,
  author    = {Dahya, Raj},
  title     = {{Choi--Cholesky}},
  subtitle  = {{Algorithms for decomposition of CPTP-maps}},
  publisher = {Hugging Face},
  doi       = {10.57967/hf/8114},
  url       = {https://doi.org/10.57967/hf/8114},
  note      = {{Code base available under \url{https://doi.org/10.57967/hf/8114}, Release vX.Y.Z}},
  year      = {2026}}

and the associated paper as

@misc{Dahya2026PreprintChoiCholesky,
  author    = {Dahya, Raj},
  title     = {{The Choi-Cholesky algorithm for completely positive maps}},
  publisher = {arXiv},
  doi       = {10.48550/arXiv.2603.19444},
  url       = {https://doi.org/10.48550/arXiv.2603.19444},
  year      = {2026}}

This code base is modularised as follows:

src/algorithms/choi_cholesky contains the algorithm presented in the paper.
src/experiments/choi_cholesky contains a numerical experiment which involves iterative
- generation of random CP-/CPTP-maps
- execution of the algorithm
- raising of errors to mark failure (i.e. no raised errors implies empirical validation).
src/examples.py contains the entry point for the application (see below).

Usage

There are three ways to use the code in this repository:

as a package;
as an open source code base;
as an open source code base using task runners.

We recommend the 1st variant for those who want to dive in. For developers/contributors the 3rd variant is useful.

System requirements

python3.10--14 (tested on python3.14)
bash or bash-like terminal

Usage as package

Install the package by setting adding this package as a dependency within your pyproject.toml for example as follows:

toml
1[project] 2name = "example" 3version = "0.0.0" 4description = 'Example code base' 5authors = [ 6 {name="me", email="me@users.noreply.git.com"}, 7] 8urls = {homepage = 'https://git.com/me/example'} 9maintainers = [ 10 {name="me", email="me@users.noreply.git.com"}, 11] 12license = 'MIT' 13readme = 'README.md' 14keywords = [ 15 "python", 16] 17classifiers = [ 18 "Programming Language :: Python :: 3", 19] 20requires-python = ">=3.11,<3.15" 21 22dependencies = [ 23 "pip>=26.0.1", 24 # third party package - replace vX.Y.Z by desired version 25 "choi-cholesky @ git+https://hf.co/raj-dahya/choi-cholesky.git@vX.Y.Z#egg=choi-cholesky", 26 # to include Rust backend 27 # "choi-cholesky[rust] @ git+https://hf.co/raj-dahya/choi-cholesky.git@vX.Y.Z#egg=choi-cholesky", 28] 29 30[dependency-groups] 31dev = [ 32 "uv>=0.11.2", 33 "ruff>=0.15.8", 34 "pytest>=9.0.2", 35 "maturin>=1.12.6", 36] 37 38[build-system] 39requires = [ 40 "setuptools>=82.0.1", 41 "wheel>=0.46.3", 42 "maturin>=1.12.6,<2.0", 43] 44build-backend = "setuptools.build_meta" 45 46[tool.pip] 47extra-index-url = []
In your python script use the package as follows

py
1import logging 2 3from choi_cholesky.algorithms.generation import * 4from choi_cholesky.algorithms.choi_cholesky import * 5from choi_cholesky.experiments.choi_cholesky import * 6 7if __name__ == "__main__": 8 # optional seed 9 seed = "1234" # or None 10 11 # set up logging 12 logging.basicConfig( 13 format="%(asctime)s $\x1b[92;1m%(name)s\x1b[0m [\x1b[1m%(levelname)s\x1b[0m] %(message)s", 14 datefmt=r"%Y-%m-%d %H:%M:%S", 15 encoding="utf-8", 16 ) 17 logging.getLogger().setLevel(logging.INFO) 18 19 # create Choi matrix of random CP-map 20 C = random_cp(10, 20, seed=seed) 21 logging.info(C.shape) # (10, 10, 20, 20) 22 23 # create Choi matrix of random CPTP-map 24 C = random_cptp(10, 20, seed=seed) 25 logging.info(C.shape) # (10, 10, 20, 20) 26 27 # run Choi-Cholesky decomposition: 28 L = algorithm_choi_cholesky(C, tol=1e-6) # algorithm in paper 29 diff = tensor_diff(tensor_multiply(L, tensor_conj(L)), C) 30 print(f"‖L·L^† – C(Φ)‖ = {diff:.4g}") 31 32 L = algorithm_choi_cholesky_modified(C, tol=1e-6) # equivalent but modified version 33 diff = tensor_diff(tensor_multiply(L, tensor_conj(L)), C) 34 print(f"‖L·L^† – C(Φ)‖ = {diff:.4g}") 35 36 # run numerical experiment to empirically verify correctness of algorithm 37 verify_choi_cholesky( 38 # d1 = dim(H1), d2 = dim(H2) 39 d1=10, 40 d2=20, 41 # number of iterations in which a CP-map Φ : L^1(H1) - L^1(H2) is defined and decomposed 42 n=100, 43 # generate random CP-maps (or CPTP-maps) in each iteration 44 map="CP", # choices: "CP", "CPTP" 45 # use the Choi-Cholesky algorithm (or the modified one) in each iteration 46 algorithm="CHOI-CHOLESKY", # choices: "CHOI-CHOLESKY", "CHOI-CHOLESKY-MODIFIED" 47 # optional seed 48 seed=seed, 49 )

Usage as open source code base

Clone the repository.
On linux/osx run the following bash commands within the repository

bash
1# create and activate virtual environment 2python3 -m venv .venv 3. .venv/bin/activate 4# install and upgrades package manager 5python3 -m pip install --upgrade pip uv 6# install depdendencies using the uv package manager 7python3 -m uv sync --compile-bytecode --no-managed-python --no-python-downloads

or for windows users

bash
1# create and activate virtual environment 2py -3 -m venv .venv 3. .venv/Scripts/activate 4# install and upgrades package manager 5python -m pip install --upgrade pip uv 6# install depdendencies using the uv package manager 7python -m uv sync --compile-bytecode --no-managed-python --no-python-downloads
Within a bash terminal activate the virtual environment

bash
1. .venv/bin/activate # for linux/osx 2. .venv/Scripts/activate # for windows
Run the script²

bash
1python3 -m src.examples --help # to display help 2python3 -m src.examples version # to display version information 3python3 -m src.examples # runs the numerical experiment with default settings 4# run the numerical experiment with custom settings 5python3 -m src.examples --algorithm ... --map ... --num ... --dim1 ... --dim2 ... --seed ...

(see below for the flag options).

Usage as open source code base with task runner

For those with the Justfile tool, setup and execution is a lot easier:

Clone the repository
Call just setup and modify the contents of the newly created .env file (viz. set PYTHON_PATH to the command for your system).
Call just build to build a virtual environment + dependencies.
Now one may call

bash
1just run-examples --help # to display help 2just run-examples version # to display version information 3 4just run-examples # runs the numerical experiment with default settings 5just run-examples --algorithm ... --map ... --num ... --dim1 ... --dim2 ... --seed ...

(see below for the flag options).

Cli-Flags

The command line interface flags for the execution of the application are as follows

Flag	Value	Description
`-a` / `--algorithm`	(default) `"CHOI-CHOLESKY"`	uses the Choi–Cholesky decomposition as in the paper
"	`"CHOI-CHOLESKY-MODIFIED"`	uses a slightly optimised variant of the Choi–Cholesky decomposition to reduce floating point errors
`-m` / `--map`	(default) `"CP"`	during each iteration of the verification generate (the Choi-matrix of) a random CP-map
"	"CPTP"	during each iteration of the verification generate (the Choi-matrix of) a random CPTP-map
`-n` / `--num`	`<integer>` (default=`100`)	number of iterations in experiment
`--dim1`	`<integer>` (default=`10`)	dimension of the "input" Hilbert space H1
`--dim2`	`<integer>` (default=`20`)	dimension of the "output" Hilbert space H2
`--seed`	`<string>` (default: `null`, examples: `"1234"`, `"abc"`, etc.)	if set, seeds the random number generator for repeatability

Rust bindings for python

An implementation in rust has been provided, which mirrors the python setup, but has the advantages of a compiled package which includes parallelisation. To use it add the dependency

toml

...
dependencies = [
    ...
    # third party package - replace vX.Y.Z by desired version
    "choi-cholesky[rust] @ git+https://hf.co/raj-dahya/choi-cholesky.git@vX.Y.Z#egg=choi-cholesky",
    ...
]
...

to your pyproject.toml manifest (see above).

One can then use the script as follows:

import logging

# import basic methods
from choi_cholesky.models.linalg.bipartite import tensor_diff
from choi_cholesky.models.linalg.bipartite import tensor_conj
from choi_cholesky.models.linalg.bipartite import tensor_multiply

# import critical methods from rust backend for improved efficiency
from choi_cholesky_rust import random_cp
from choi_cholesky_rust import random_cptp
from choi_cholesky_rust import algorithm_choi_cholesky
from choi_cholesky_rust import algorithm_choi_cholesky_modified
from choi_cholesky_rust import verify_choi_cholesky

if __name__ == "__main__":
    seed = "1234"
    # set up logging
    logging.basicConfig(
        format="%(asctime)s $\x1b[92;1m%(name)s\x1b[0m [\x1b[1m%(levelname)s\x1b[0m] %(message)s",
        datefmt=r"%Y-%m-%d %H:%M:%S",
        encoding="utf-8",
    )
    logging.getLogger().setLevel(logging.INFO)

    # create Choi matrix of random CP-map
    # NOTE: underlying linear algebraic operation (computation of operator norm) to ensure C is a contraction is subject to correction.
    try:
        C = random_cp(10, 20, seed=seed)
        logging.info(C.shape) # (10, 10, 20, 20)

    except Exception as err:
        logging.error(err)

    # create Choi matrix of random CPTP-map
    C = random_cptp(10, 20, seed=seed)
    logging.info(C.shape) # (10, 10, 20, 20)

    # run Choi-Cholesky decomposition:
    L = algorithm_choi_cholesky(C, tol=1e-6) # algorithm in paper
    diff = tensor_diff(tensor_multiply(L, tensor_conj(L)), C)
    print(f"‖L·L^† – C(Φ)‖ = {diff:.4g}")

    L = algorithm_choi_cholesky_modified(C, tol=1e-6) # equivalent but modified version
    diff = tensor_diff(tensor_multiply(L, tensor_conj(L)), C)
    print(f"‖L·L^† – C(Φ)‖ = {diff:.4g}")

    # run numerical experiment to empirically verify correctness of algorithm
    # NOTE: using rust backend, this runs the experiments in parallel
    verify_choi_cholesky(
        # d1 = dim(H1), d2 = dim(H2)
        d1=10,
        d2=20,
        # number of iterations in which a CP-map Φ : L^1(H1) - L^1(H2) is defined and decomposed
        n=1000,
        # generate random CP-maps (or CPTP-maps) in each iteration
        map="CP", # choices: "CP", "CPTP"
        # use the Choi-Cholesky algorithm (or the modified one) in each iteration
        algorithm="CHOI-CHOLESKY", # choices: "CHOI-CHOLESKY", "CHOI-CHOLESKY-MODIFIED"
        # optional seed
        seed=seed,
    )

Footnotes

the version in note can be replaced by given version or commit id used. ↩
On windows within the venv one must use python instead of python3 ↩

raj-dahya/choi-cholesky