tb3py - Python Wrapper for ThreeBodyTB.jl
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
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
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
Links
- Main github of ThreeBodyTB.jl
- Paper: PhysRevMaterials.7.044603
- Main documentation
- Main tutorial
- My NIST page
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.