Skip to main content

pele : Python Energy Landscape Explorer

Build Status Coverage Status

Tools for global optimization, attractor finding and energy landscape exploration.

Source code: https://github.com/pele-python/pele

https://raw.githubusercontent.com/pele-python/pele/main/lj38_gmin_dgraph.png

Images: The global minimum energy structure of a 38 atom Lennard-Jones cluster. On the right is a disconnectivity graph showing a visualization of the energy landscape. The competing low energy basins are shown in color.

pele started as a python partial-rewriting of GMIN, OPTIM, and PATHSAMPLE: fortran programs written by David Wales of Cambridge University and collaborators (http://www-wales.ch.cam.ac.uk/software.html). The current version also has undergone major development at the Martiniani Lab at New York University (https://martinianilab.org/software/).

Description

pele has tools for energy minimization, global optimization, saddle point (transition state) search, data analysis, visualization and much more. Some of the algorithms implemented are:

  1. Basinhopping global optimization

  2. Potentials (Lennard-Jones, Morse, Hertzian, etc.)

  3. LBFGS minimization (plus other minimizers)

  4. Attractor identification (Mixed Descent, CVODE)

  5. Single ended saddle point search: - Hybrid Eigenvector Following - Dimer method

  6. Double ended saddle point search - Nudged Elastic Band (NEB) - Doubly Nudged Elastic Band (DNEB)

  7. Disconnectivity Graph visualization

  8. Structure alignment algorithms

  9. Thermodynamics (e.g. heat capacity) via the Harmonic Superposition Approximation

  10. Transition rates analysis

Installation

PyPI wheels support Python 3.11–3.14 on Linux x86_64 (glibc 2.28 or newer) and macOS 14 or newer on Intel and Apple Silicon. Windows is not supported:

$ pip install pele

Building from source needs C/C++/Fortran compilers, SUNDIALS, Eigen, LAPACK headers, and OpenMP. A conda environment can supply these dependencies.

$ conda create -n pele -c conda-forge python compilers sundials eigen blas-devel
$ conda activate pele
$ pip install git+https://github.com/pele-python/pele

Python 3.11 or newer is required. CI tests Python 3.11 and 3.14 on Linux and macOS.

If the machine already has gcc, g++ and gfortran (e.g. sudo apt install gcc g++ gfortran), leave out compilers for a much smaller environment. On macOS use homebrew’s gcc (Apple clang has no OpenMP or Fortran):

$ brew install gcc openblas
$ CC=gcc-15 CXX=g++-15 FC=gfortran-15 pip install git+https://github.com/pele-python/pele

Optional: scikit-sparse (sparse Cholesky for rate calculations) and pymol-open-source (viewing structures). The GUI (pele.gui) uses PyQt5 and PyOpenGL. Install them before building so Meson generates the forms:

$ pip install PyQt5 PyOpenGL
$ pip install --no-build-isolation '.[gui]' -Csetup-args=-Dgui=enabled

The OpenGL viewer also needs the system GLU and GLUT libraries (on Ubuntu, sudo apt install libglu1-mesa libglut3.12). Launch an example with python examples/gui/ljsystem.py.

Optional: LAMMPS potentials (pele.potentials.LAMMPSPotential and the pele.systems.AtomicClusterLAMMPS system). Install the LAMMPS Python package before building and the compiled interface is built too; without a build it falls back to a pure Python version:

$ pip install 'lammps[mpi]'
$ pip install --no-build-isolation '.[lammps]' -Csetup-args=-Dlammps=enabled

See examples/gui/lammps_ljsystem.py for a GUI example.

Development

pele is built with meson through meson-python. From a clone, in the same environment:

$ pip install meson-python meson ninja cython numpy
$ pip install --no-build-isolation -e .   # editable

Build options are meson options, passed with -Csetup-args=..., e.g. pip install . -Csetup-args=-Dbuildtype=debug:

  • -Dbuildtype=debug (default release)

  • -Dcvode=disabled: no CVODE / attractor identification; some tests will fail

  • -Dnative=true: opt in to -march=native for local builds. The default is false, for binaries that run on other machines.

  • -Dgui=enabled / disabled (default auto): generate the PyQt5 GUI forms; needs pyuic5 and pyrcc5

  • -Dlammps=enabled / disabled (default auto): build the compiled LAMMPS potential; needs the lammps Python package

The editable install keeps its build in build/; pass -Cbuild-dir=... to choose another directory. Editable means code edits will lead to fresh rebuild for C++ code the next time you import pele. python edits will automatically reflect without compilation

SUNDIALS, Eigen and LAPACK are taken from the active conda environment (or, without one, from the system, e.g. sudo apt install libsundials-dev libeigen3-dev liblapack-dev liblapacke-dev). pele links LAPACK itself; it needs the LAPACKE package only for the header lapack.h (conda’s blas-devel provides both). SUNDIALS must be built in double precision.

A CPATH/PYTHONPATH pointing at a pele clone takes precedence over the installed package. If a build fails, remove the build directory before trying again:

$ rm -rf build

Documentation

docs are at https://pele-python.github.io/pele/.

Tests

The project uses GitHub Actions for continuous integration (CI) testing on both Linux and macOS.

The C++ tests use GoogleTest (the cpp_tests/gtest submodule, or a system GoogleTest) and need no Python packages:

$ git submodule update --init --recursive
$ meson setup build-tests -Dpython=disabled -Dtests=true -Dbuildtype=debug
$ meson test -C build-tests

Add -Db_sanitize=address for AddressSanitizer or -Db_coverage=true for coverage. On macOS, prefix meson setup with CC=gcc-15 CXX=g++-15. The benchmarks in cpp_tests/source/benchmarks build on request, e.g. ninja -C build-tests cpp_tests/bench_lj.

To run the Python tests on an installed pele:

$ pip install pytest
$ OMP_NUM_THREADS=1 pytest --pyargs pele

or pytest pele/ from a clone with an editable install. For coverage reporting (as in CI), add --cov=pele --cov-report=term-missing.

Contributing

See CONTRIBUTING.md.

Metadata

Release files for pele 0.1.2

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

Source distribution (sdist)

Source distribution for pele 0.1.2
File Size Uploaded
pele-0.1.2.tar.gz 3.6 MB Details

Built distributions (wheels)

Table of built distributions (wheels) for pele 0.1.2
File
pele-0.1.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details
pele-0.1.2-cp314-cp314-macosx_14_0_x86_64.whl CPython 3.14 CPython 3.14 macOS 14.0+ x86-64 Details
pele-0.1.2-cp314-cp314-macosx_14_0_arm64.whl CPython 3.14 CPython 3.14 macOS 14.0+ ARM64 Details
pele-0.1.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.13 CPython 3.13 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details
pele-0.1.2-cp313-cp313-macosx_14_0_x86_64.whl CPython 3.13 CPython 3.13 macOS 14.0+ x86-64 Details
pele-0.1.2-cp313-cp313-macosx_14_0_arm64.whl CPython 3.13 CPython 3.13 macOS 14.0+ ARM64 Details
pele-0.1.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details
pele-0.1.2-cp312-cp312-macosx_14_0_x86_64.whl CPython 3.12 CPython 3.12 macOS 14.0+ x86-64 Details
pele-0.1.2-cp312-cp312-macosx_14_0_arm64.whl CPython 3.12 CPython 3.12 macOS 14.0+ ARM64 Details
pele-0.1.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details
pele-0.1.2-cp311-cp311-macosx_14_0_x86_64.whl CPython 3.11 CPython 3.11 macOS 14.0+ x86-64 Details
pele-0.1.2-cp311-cp311-macosx_14_0_arm64.whl CPython 3.11 CPython 3.11 macOS 14.0+ ARM64 Details

Total release size: 238.8 MB

Release files / pele-0.1.2.tar.gz

Download URL pele-0.1.2.tar.gz
Size 3.6 MB
Tags Source
SHA-256 checksum
How to use checksums
f9a91378ecb3464074204a67c6e7d5e7796d1adc4329d3bc69c741afbd91cb0c
BLAKE2b-256 checksum
How to use checksums
9f72e32115f657a21806b2097de22f01e3e6edc2b4934825f57a43ec4e64ccb4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pele-0.1.2-cp314-cp314-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 23.2 MB
Tags CPython 3.14 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
18278a593a39de32754b1b4a6f2c223c9d769180d682629c509ba641b102971c
BLAKE2b-256 checksum
How to use checksums
4ef13313e31019894206158a3a1c18a5713d5e3205eac4b5bfd7bf7f514911d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp314-cp314-macosx_14_0_x86_64.whl

Download URL pele-0.1.2-cp314-cp314-macosx_14_0_x86_64.whl
Size 20.7 MB
Tags CPython 3.14 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
dca436162f8fe789f5ab70bcaf0bf1acf476737ddca8fc518fad44127ed2b857
BLAKE2b-256 checksum
How to use checksums
ad42124778fa0b3f94773b35edd21fa3867fddc9bb7bb509e8d025cb87be5b06
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp314-cp314-macosx_14_0_arm64.whl

Download URL pele-0.1.2-cp314-cp314-macosx_14_0_arm64.whl
Size 14.9 MB
Tags CPython 3.14 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
2c48a15fde9e587391735ac8a7e2431b2ef68985e78ebaa7d444f1603727e001
BLAKE2b-256 checksum
How to use checksums
9e04656023137dc5b0f136f3a771f7f60913f3a824d43a9579cc84e334cda207
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pele-0.1.2-cp313-cp313-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 23.2 MB
Tags CPython 3.13 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
8680ebab3c70baf04b9c5b1497ea2f89cda51b54680de1d6ef812f3bc5f3f314
BLAKE2b-256 checksum
How to use checksums
18560d67ba93f9693a7afd00f31c37904a4002983bfac32fe1774e064901bb4b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp313-cp313-macosx_14_0_x86_64.whl

Download URL pele-0.1.2-cp313-cp313-macosx_14_0_x86_64.whl
Size 20.7 MB
Tags CPython 3.13 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
2ac1d59e60bd04a4c35ea9dd9d5bf5e9d158f80233784e09602b0f47d441f59a
BLAKE2b-256 checksum
How to use checksums
dd026d5ba754f58b88c845afffb11e2ab662300e9b4409c8c33bb1f6ec30cc59
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp313-cp313-macosx_14_0_arm64.whl

Download URL pele-0.1.2-cp313-cp313-macosx_14_0_arm64.whl
Size 14.9 MB
Tags CPython 3.13 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
861a2028f4186de8bed2b438424002dde92ca7025a3f5129de75502a1aba3da3
BLAKE2b-256 checksum
How to use checksums
578e8cc1522cfa5127071fcc247aa1298edf74077cf69a76db1abdb8c5da44e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pele-0.1.2-cp312-cp312-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 23.2 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
904988af3399e22c47d2504efc90e996c83fa5e6da8b96348a945684d9b72358
BLAKE2b-256 checksum
How to use checksums
e4ce86a77b7acf561e3a79f0f0640ee74008df5bf567604f66f9ca1465fd137d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp312-cp312-macosx_14_0_x86_64.whl

Download URL pele-0.1.2-cp312-cp312-macosx_14_0_x86_64.whl
Size 20.7 MB
Tags CPython 3.12 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
489e77d08ef47fdd4c7f5962470f693ab3076567d21a02c0b8c2d8cb47daa5a6
BLAKE2b-256 checksum
How to use checksums
ffe918aaddcffdf01f26643f4b14ef4d7d64c80d747144438fbf0d394e42ff54
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp312-cp312-macosx_14_0_arm64.whl

Download URL pele-0.1.2-cp312-cp312-macosx_14_0_arm64.whl
Size 14.9 MB
Tags CPython 3.12 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
e02ecfc5d3264fd3c6a1e3831da9b3d289c080c5c9218ac141b3d662081ab9f8
BLAKE2b-256 checksum
How to use checksums
c3122cb77119fb654af12f4a571593b6a83fb7f750955b566396c945525c05a3
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL pele-0.1.2-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 23.2 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
e15d1e9ffefc0f0e971bced43bc821584e43ab57b65fb8e07d083d9405244be9
BLAKE2b-256 checksum
How to use checksums
690eb64912941e6b8c7997c3b57a20d15ba3506d25ae8fee3b8be94a9a44db75
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp311-cp311-macosx_14_0_x86_64.whl

Download URL pele-0.1.2-cp311-cp311-macosx_14_0_x86_64.whl
Size 20.7 MB
Tags CPython 3.11 macOS 14.0+ x86-64
SHA-256 checksum
How to use checksums
5b05a542a72bbf70bea69012c26be9ec4a3766f41d288cd629e8ff5c40024dba
BLAKE2b-256 checksum
How to use checksums
bce40acbafc5e43da962830f0706494f623d278895988df5785d7615c7a1de35
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release files / pele-0.1.2-cp311-cp311-macosx_14_0_arm64.whl

Download URL pele-0.1.2-cp311-cp311-macosx_14_0_arm64.whl
Size 14.9 MB
Tags CPython 3.11 macOS 14.0+ ARM64
SHA-256 checksum
How to use checksums
b1d85a61c11773cf017539a759e2fcecb3116618bcb86c8f3194b818814187d9
BLAKE2b-256 checksum
How to use checksums
1588041d9f0e1b4465f4cb478a72a433e9386e3da7b47629ecfce41ad38d06fe
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 12, 2026.

Transparency log

Release history Release notifications | RSS feed

This release

0.1.2 This release

13 release files

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