Skip to main content

Atomic and Molecular Cluster Energy Surface Sampler

Project description

Atomic and Molecular Cluster Energy Surface Sampler (AMCESS)

Exploration of the Potential Energy Surface (PES) of molecules or atoms clusters is a crucial step to analyze physical–chemistry properties and processes. The Atomic and Molecular Energy Surface Sampler (AMCESS) is an end-to-end package implemented in Python 3.9 to generate candidate structures for the critical points sampling of the PES. The amcess main purpose is to be a user friendly package, easy to install, import, and run, available in most platforms and open-source. As a Python module, amcess can be integrated into any workflow. This package has code reviews with unit testing and continuous integration, code coverage tools, and automatically keeps documentation up–to–date.

Molecular cluster of ibuprofen and six water molecules [doi: 10.1063/1.4874258]


The amcess package uses simple input files and automates common procedures to explore the PES using the Simulated Annealing, Simplicial Homology Global Optimiza- tion (SHGO), and Bayesian Optimization to generate candidate structures for any kind of critical point, such as local minima or transition states. The package also allows the user to perform local searches around defined regions. The PES is generated computing the electronic energy using standard and powerful quantum chemistry packages such as PySCF and Psi4, also implemented in Python.

Technical Documentation

Technical documents behind this project can be accessed here.


First you should install the required python packages

  - attrs==21.2
  - scipy==1.7.1
  - numpy==1.21.2
  - pyscf==1.7.6.post1
  - h5py==3.1.0
  - pyberny==0.6.3
  - geomeTRIC==
  - GPyOpt==1.2.6
  - pyDOE==0.3.8
  - matplotlib==3.4.2

check the file requirements.txt. For developer, you should install requirements_dev.txt.


AMCESS is Python 3.9 package

  1. Install virtual environment:

    python -m venv venv

  2. Activate virtual environment:

    source venv/bin/activate

  3. Install the packages:

    pip install amcess

  4. Run AMCESS (check some examples below)

  5. For developer only, install dependencies:

    pip install -r requirements.txt -r requirements_dev.txt

  6. Run all test:



A detail workflow is provide into workflow directory. It has a list of Jupyter notebook with detail examples about AMCESS tools and capabilities.


  1. Getting starting with atoms and molecules properties.
    • Notebook (binder): 01_importing_atoms_and_molecules.ipynb
  2. Translating and rotating atoms and molecules.
    • Notebook (binder): 02_move_rotate_molecules.ipynb
  3. Moving Molecules randomly from a Cluster.
    • Notebook (binder): 03_move_rotate_cluster.ipynb
  4. Freezing any molecule and redefine its sphere center.
    • Notebook (binder): 04_freeze_molecule_redefine_center.ipynb
  5. Initialize a cluster avoiding atomic overlapping
    • Notebook (binder): 05_initialize_cluster_and_move_molecule.ipynb


Some of the ideas to keep growing are:

  • Integration with RDKit (multiple format input)
  • Results: geometrical analysis (clustering, k-nearest, k-means, etc.)


The easiest way to get help with the project is to join the #amcess channel on Discord.

We hang out there and you can get real-time help with your projects. The other good way is to open an issue on GitLab.


GNU General Public License v3 (GLPv3)

Authors and Acknowledgment

Main authors: Alejandra Mendez, Juan Jose Aucar, Daniel Bajac, César Ibargüen, Andy Zapata, Edison Florez (

Project Status

Under development

ASCEC (FORTRAN 77 version)

A previous version of AMCESS, called ASCEC [1] (spanish acronym Annealing Simulado con Energía Cuántica) was written in FORTRAN77 and was successfully used in the wide range of research and academic applications. From atomic cluster to molecular cluster, the ASCEC package has produced novel results (structure never seen before) published in the literature. Read more on ASCEC publications.

You could check the directory ASCECV3



[1] J Pérez and A Restrepo. Ascec v–02: annealing simulado con energía cuántica. Property, development and implementation: Grupo de Química–Física Teórica, Instituto de Química, Universidad de Antioquia: Medellín, Colombia, 2008.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

amcess-0.1.1.tar.gz (40.3 kB view hashes)

Uploaded source

Built Distribution

amcess-0.1.1-py3-none-any.whl (37.5 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page