Skip to main content

tb3py - Python Wrapper for ThreeBodyTB.jl

logo

This package is a simple python wrapper for ThreeBodyTB.jl that makes installing and using the code within python simple. It is not necessary to understand any Julia, and you get full access to the code.

ThreeBodyTB.jl (see https://github.com/usnistgov/ThreeBodyTB.jl) is a Julia package to perform tight binding calculations. It is based on the method described in PhysRevMaterials.7.044603.

Usage

Open In Colab

The documentation for ThreeBodyTB.jl covers detailed usage of the main julia code. The python wrapper can access any function from ThreeBodyTB.jl by prepending tb3.jl. . For example, the exported function makecrys from ThreeBodyTB.jl can be accessed as follows:

>>> import tb3py as tb3
>>> c = tb3.jl.makecrys("POSCAR_example")
>>> c
Julia:
Units: Å

A1=     2.60000  2.60000  0.00000
A2=     2.60000  0.00000  2.60000
A3=     0.00000  2.60000  2.60000

Si   0.00000  0.00000  0.00000
Si   0.25000  0.25000  0.25000

>>>

Using tb3.jl.ThreeBodyTB.makecrys also works, and that syntax works for non-exported functions.

An energy calculation and band structure calculation can be performed as

>>> en, tbc, flag = tb3.jl.scf_energy(c)
>>> tb3.jl.plot_bandstr_dos(tbc)
>>> tb3.jl.savefig("t.pdf")

which will produce output like

bandstructure and dos

Basically, you need to write tb3.jl. before normal julia commands. A tutorial introducing relevant commands for code users is available here, it should be possible to access all that functionality from python.

The code can also convert between numpy and julia objects fine. See:

>>> import numpy as np
>>> A = np.eye(3) * 10
>>> coords = np.zeros((1,3))
>>> atoms = ["Ga"]
>>> tb3.jl.makecrys(A, coords, atoms)
Julia:
Units: Å

A1=     10.00000  0.00000  0.00000
A2=     0.00000  10.00000  0.00000
A3=     0.00000  0.00000  10.00000

Ga   0.00000  0.00000  0.00000

>>>

Overloaded operators (slightly advanced)

In some cases ThreeBodyTB can use overloaded operators to manipulate crystal structures, including generating supercells and scaling by a constant. It is possible to access this syntax in python using seval like this:

>>> from juliacall import Main as jl
>>> jl.c = c #c is a crystal object visible to python, we are making it visible to jl
>>> jl.seval("(c * 3.0)")
Julia:
Units: Å

A1=     7.80000  7.80000  0.00000
A2=     7.80000  0.00000  7.80000
A3=     0.00000  7.80000  7.80000

Si   0.00000  0.00000  0.00000
Si   0.25000  0.25000  0.25000

>>> jl.seval("(c * [2,2,2])")
Julia:
Units: Å

A1=     5.20000  5.20000  0.00000
A2=     5.20000  0.00000  5.20000
A3=     0.00000  5.20000  5.20000

Si   0.00000  0.00000  0.00000
Si   0.12500  0.12500  0.12500
Si   0.00000  0.00000  0.50000
Si   0.12500  0.12500  0.62500
Si   0.00000  0.50000  0.00000
Si   0.12500  0.62500  0.12500
Si   0.00000  0.50000  0.50000
Si   0.12500  0.62500  0.62500
Si   0.50000  0.00000  0.00000
Si   0.62500  0.12500  0.12500
Si   0.50000  0.00000  0.50000
Si   0.62500  0.12500  0.62500
Si   0.50000  0.50000  0.00000
Si   0.62500  0.62500  0.12500
Si   0.50000  0.50000  0.50000
Si   0.62500  0.62500  0.62500

Installation

To install, clone the repository and run a setup command.

git clone git@github.com:usnistgov/tb3py.git
cd tb3py
pip install -e .

export JULIA_NUM_THREADS=1
export PYTHON_JULIACALL_HANDLE_SIGNALS=yes

This will install julia if necessary to run the backend (julia version 1.12+ is necessary). The code will take a while to install and precompile (10+ minutes) the first time you import it. This process should cache the most computationally expensive compilation, but there will still be a small delay the first time you run a function in a given session.

The two environment variables are to prevent issues with multithreading between python and Julia.

Author, Links, Release Notes

Release notes

There was a major breaking reorg of this code on 10/27/2026. The previous version is archived under branch old_version.

Author

Good luck. Let me know if you have any problems.

kevin.garrity@nist.gov
Kevin F. Garrity
Material Data Division: 641.03
Material Measurement Laboratory
National Institute of Standards and Techonology (NIST)
Gaithersburg, MD

Metadata

Release files for tb3py 2026.11.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tb3py 2026.11.3
File Size Uploaded Provenance Actions
tb3py-2026.11.3.tar.gz 4.7 kB Without provenance Details for tb3py-2026.11.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tb3py 2026.11.3
File Interpreter ABI Platform Actions
tb3py-2026.11.3-py3-none-any.whl Python 3 none any Details for tb3py-2026.11.3-py3-none-any.whl

Total release size: 10.0 kB

Release files / tb3py-2026.11.3.tar.gz

Download URL tb3py-2026.11.3.tar.gz
Size 4.7 kB
Tags Source
SHA-256 checksum
How to use checksums
49ad4af27d51c9a3a93a556a16c0727ac8eb225d474ae5682516f87f35875426
BLAKE2b-256 checksum
How to use checksums
9b41f078e16893898af185b9b77d53ab793935e463ad27e85443120618fdc138
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.11

Release files / tb3py-2026.11.3-py3-none-any.whl

Download URL tb3py-2026.11.3-py3-none-any.whl
Size 5.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
5bdd4108426c0f136949b3a82f34e12fb1228031b1ed90fabebff0392d90d74f
BLAKE2b-256 checksum
How to use checksums
d2fef6ccd34c5ba3a1e69d5cf64daf45e58a7d36e0f1185c207de601f5357381
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.11.11

Security for tb3py 2026.11.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page