<!-- [](https://www.python.org/downloads/release/python-390/)
[](https://gitlab.com/ADanianZE/ascec/-/commits/main)
[](https://coveralls.io/gitlab/ADanianZE/ascec?branch=main)
[](https://gitlab.com/ADanianZE/ascec/-/commits/main)
[](https://mybinder.org/v2/gl/ADanianZE%2Fascec/main?filepath=workflow%2F01_importing_atoms_and_molecules.ipynb)
[](http://mypy-lang.org/)
[](https://github.com/psf/black)
 -->
<!--  -->
<div align="center">
<a href=http://mypy-lang.org/>
<img src="http://www.mypy-lang.org/static/mypy_badge.svg"></a>
<a href=https://github.com/psf/black>
<img src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
<br>
<a href=https://www.python.org/downloads/release/python-390/>
<img src=https://img.shields.io/badge/python-3.9-blue.svg></a>
<a href=https://www.gnu.org/licenses/gpl-3.0>
<img src="https://img.shields.io/badge/License-GPLv3-blue.svg"></a>
<a href=https://mybinder.org/v2/gl/ADanianZE%2Fascec/main?filepath=workflow%2F01_importing_atoms_and_molecules.ipynb>
<img src="https://mybinder.org/badge_logo.svg"></a>
<br>
<a href=https://img.shields.io/gitlab/pipeline/ADanianZE/ascec/main?style=plastic>
<img src="https://img.shields.io/gitlab/pipeline/ADanianZE/ascec/main?style=plastic"></a>
<a href=https://gitlab.com/ADanianZE/ascec/-/commits/main>
<img src="https://gitlab.com/ADanianZE/ascec/badges/main/pipeline.svg"></a>
<a href=https://img.shields.io/gitlab/coverage/ADanianZE/ascec/main?style=plastic>
<img src="https://img.shields.io/gitlab/coverage/ADanianZE/ascec/main?style=plastic"></a>
<a href=https://coveralls.io/gitlab/ADanianZE/ascec?branch=main>
<img src="https://coveralls.io/repos/gitlab/ADanianZE/ascec/badge.svg?branch=main"></a>
</div>
---
<div align="center">
<a href="Atomic and Molecular Cluster Energy Surface Sampler">
<img width="400" height="200" src="https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/amcess_logo.png"></a>
<br>
</div>
---
<div align="center">
<h1> Atomic and Molecular Cluster Energy Surface Sampler (AMCESS) </h1>
</div>
Exploration of the Potential Energy Surface (PES) of molecular or atomic clusters is
a crucial step in analyzing 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 on 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.
<div align="center">
<img width="200" height="80" src="https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/ibuprofen.png" VSPACE=50 HSPACE=10>
<img width="350" height="200" src="https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/ibu_w6_white.gif" HSPACE=20>
<br>
Molecular cluster of ibuprofen and six water molecules
[<a href="http://www.doi.org/10.1063/1.4874258">doi: 10.1063/1.4874258</a>]
<br>
<br>
</div>
### Description
The amcess package uses simple input files and automates common procedures to explore the PES using the Simulated Annealing, Simplicial Homology Global Optimization (SHGO), and Bayesian Optimization to generate candidate structures for any kind of critical points, such as local minima or transition states. The package also allows the user to perform local searches around defined regions. The PES is generated by computing the electronic energy using standard and powerful quantum chemistry packages such as PySCF and Psi4, also implemented in Python.
Read more about the project in the [documentation](https://github.com/e-florez/amcess/blob/main/docs/white_paper/amcess_white_paper.pdf).
### Technical Documentation
Technical documents behind this project can be accessed [here](https://adanianze.gitlab.io/amcess).
### Requirements
First, you should install the required Python packages
```
attrs>=23.2.0
scipy>=1.12.0
numpy==1.23.1
pyscf>=2.5.0
h5py>=3.1.0
pyberny>=0.6.3
geomeTRIC>=0.9.7.2
GPyOpt>=1.2.6
pyDOE>=0.3.8
matplotlib>=3.8.3
matplotlib-inline>=0.1.6
```
To use Jupyter Notebook
```
py3Dmol>=2.0.4
notebook>=6.5.6
notebook_shim>=0.2.4
jupyter>=1.0.0
ipykernel>=6.29.3
rise>=5.7.1
```
check the file `requirements.txt`. For developers, you should install `requirements_dev.txt`.
### Installation
AMCESS is a **Python 3.9** package
1. Install virtual environment:
`python -m venv <VirtualEnvName>`
2. Activate virtual environment:
`source <VirtualEnvName>`/bin/activate`
3. Install the packages:
1. after cloning this repository
`pip install .`
2. or directly from PyPI
`pip install amcess`
4. Run AMCESS (check some examples below). Additionally, you can install `requirements.txt` to use Jupyter notebooks.
For developers,
1. install dependencies:
`pip install -r requirements.txt -r requirements_dev.txt`
2. Run all test:
`tox`
### Usage
A detailed workflow is provided in the `workflow` directory. It has a list of Jupyter notebooks with detailed examples of AMCESS tools and capabilities.
Workflow ([Binder](https://mybinder.org/v2/gl/ADanianZE%2Famcess/main?labpath=https%3A%2F%2Fgitlab.com%2FADanianZE%2Famcess%2F-%2Ftree%2Fmain%2Fworkflow)):
1. Getting started with atoms and molecules properties.
- `01_importing_atoms_and_molecules.ipynb`
2. Translating and rotating atoms and molecules.
- `02_move_rotate_molecules.ipynb`
3. Moving Molecules randomly from a Cluster.
- `03_move_rotate_cluster.ipynb`
4. Freezing any molecule and redefining its sphere center.
- `04_freeze_molecule_redefine_center.ipynb`
5. Initialize a cluster avoiding atomic overlapping
- `05_initialize_cluster_and_move_molecule.ipynb`
## Roadmap
Some of the ideas to keep growing are:
- Integration with **RDKit** (multiple format input)
- Results: geometrical analysis (clustering, k-nearest, k-means, etc.)
## Contributing
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.
- GitHub: https://github.com/e-florez/amcess/issues
- Discord: https://discord.gg/vxQQCjpg
### License
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 (_edisonffh@mail.com_)
### Project Status
Under development
---
## ASCEC (FORTRAN 77 version)
A previous version of AMCESS, called ASCEC [[1]](#1) (Spanish acronym
Annealing Simulado con Energía Cuántica) was written in FORTRAN77 and
was successfully used in a 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](https://scholar.google.com/scholar?start=0&q=%22ascec%22,+annealing&hl=en&as_sdt=0,5).
You could check the directory [ASCECV3](https://gitlab.com/ADanianZE/ascec/-/tree/main/ASCECV3)
```
ASCECV3/
|---papers/
|---p_ascec/
|---examples/
|---adf
|---dalton
|---g03
|---gamess
|---nwchem
```
### References
<div style=font-size:12px>
<a id="1">[1]</a>
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.
<br>
</div>
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/ADanianZE/amcess",
"name": "amcess2024",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "Atomic Cluster, Molecular Cluster, optimization, Potential Energy Surface, PES, Monte Carlo, Simulated Annealing, Bayesian Optimization",
"author": " Edison Florez, Andy Zapata, Daniel Bajac, Alejandra Mendez, Cesar Ibarguen, Jos\u00e9 Aucar ",
"author_email": " edisonffhc@gmail.com, danianescobarv@gmail.com ",
"download_url": "https://files.pythonhosted.org/packages/ba/a1/5c2bdb8e4733a1f048b326fd0e45c02817397fbd12019449b93112f2ebe1/amcess2024-0.1.2a20.tar.gz",
"platform": null,
"description": "<!-- [](https://www.python.org/downloads/release/python-390/)\n\n[](https://gitlab.com/ADanianZE/ascec/-/commits/main)\n\n[](https://coveralls.io/gitlab/ADanianZE/ascec?branch=main)\n[](https://gitlab.com/ADanianZE/ascec/-/commits/main)\n[](https://mybinder.org/v2/gl/ADanianZE%2Fascec/main?filepath=workflow%2F01_importing_atoms_and_molecules.ipynb)\n\n[](http://mypy-lang.org/)\n[](https://github.com/psf/black)\n -->\n\n<!--  -->\n\n<div align=\"center\">\n <a href=http://mypy-lang.org/>\n <img src=\"http://www.mypy-lang.org/static/mypy_badge.svg\"></a>\n <a href=https://github.com/psf/black>\n <img src=\"https://img.shields.io/badge/code%20style-black-000000.svg\"></a>\n <br>\n <a href=https://www.python.org/downloads/release/python-390/>\n <img src=https://img.shields.io/badge/python-3.9-blue.svg></a>\n <a href=https://www.gnu.org/licenses/gpl-3.0>\n <img src=\"https://img.shields.io/badge/License-GPLv3-blue.svg\"></a>\n <a href=https://mybinder.org/v2/gl/ADanianZE%2Fascec/main?filepath=workflow%2F01_importing_atoms_and_molecules.ipynb>\n <img src=\"https://mybinder.org/badge_logo.svg\"></a>\n <br> \n <a href=https://img.shields.io/gitlab/pipeline/ADanianZE/ascec/main?style=plastic>\n <img src=\"https://img.shields.io/gitlab/pipeline/ADanianZE/ascec/main?style=plastic\"></a>\n <a href=https://gitlab.com/ADanianZE/ascec/-/commits/main>\n <img src=\"https://gitlab.com/ADanianZE/ascec/badges/main/pipeline.svg\"></a>\n <a href=https://img.shields.io/gitlab/coverage/ADanianZE/ascec/main?style=plastic>\n <img src=\"https://img.shields.io/gitlab/coverage/ADanianZE/ascec/main?style=plastic\"></a>\n <a href=https://coveralls.io/gitlab/ADanianZE/ascec?branch=main>\n <img src=\"https://coveralls.io/repos/gitlab/ADanianZE/ascec/badge.svg?branch=main\"></a>\n</div>\n\n---\n\n<div align=\"center\">\n <a href=\"Atomic and Molecular Cluster Energy Surface Sampler\">\n <img width=\"400\" height=\"200\" src=\"https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/amcess_logo.png\"></a>\n <br>\n</div>\n\n---\n\n<div align=\"center\">\n <h1> Atomic and Molecular Cluster Energy Surface Sampler (AMCESS) </h1>\n</div>\n\nExploration of the Potential Energy Surface (PES) of molecular or atomic clusters is\na crucial step in analyzing physical\u2013chemistry properties and processes. The Atomic and\nMolecular Energy Surface Sampler (AMCESS) is an end-to-end package implemented\nin Python 3.9 to generate candidate structures for the critical points sampling of the\nPES. The amcess main purpose is to be a\nuser-friendly package, easy to install, import, and run, available on most platforms and\nopen-source. As a Python module, amcess can be integrated into any workflow. This\npackage has code reviews with unit testing and continuous integration, code coverage\ntools, and automatically keeps documentation up\u2013to\u2013date.\n\n<div align=\"center\">\n <img width=\"200\" height=\"80\" src=\"https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/ibuprofen.png\" VSPACE=50 HSPACE=10>\n <img width=\"350\" height=\"200\" src=\"https://gitlab.com/ADanianZE/amcess/-/raw/main/docs/source/_static/ibu_w6_white.gif\" HSPACE=20>\n <br>\n Molecular cluster of ibuprofen and six water molecules\n [<a href=\"http://www.doi.org/10.1063/1.4874258\">doi: 10.1063/1.4874258</a>]\n <br>\n <br>\n</div>\n\n### Description\n\nThe amcess package uses simple input files and automates common procedures to explore the PES using the Simulated Annealing, Simplicial Homology Global Optimization (SHGO), and Bayesian Optimization to generate candidate structures for any kind of critical points, such as local minima or transition states. The package also allows the user to perform local searches around defined regions. The PES is generated by computing the electronic energy using standard and powerful quantum chemistry packages such as PySCF and Psi4, also implemented in Python.\n\nRead more about the project in the [documentation](https://github.com/e-florez/amcess/blob/main/docs/white_paper/amcess_white_paper.pdf).\n\n### Technical Documentation\n\nTechnical documents behind this project can be accessed [here](https://adanianze.gitlab.io/amcess).\n\n### Requirements\n\nFirst, you should install the required Python packages\n\n```\n attrs>=23.2.0\n scipy>=1.12.0\n numpy==1.23.1\n pyscf>=2.5.0\n h5py>=3.1.0\n pyberny>=0.6.3\n geomeTRIC>=0.9.7.2\n GPyOpt>=1.2.6\n pyDOE>=0.3.8\n matplotlib>=3.8.3\n matplotlib-inline>=0.1.6\n```\n\nTo use Jupyter Notebook\n\n```\n py3Dmol>=2.0.4\n notebook>=6.5.6\n notebook_shim>=0.2.4\n jupyter>=1.0.0\n ipykernel>=6.29.3\n rise>=5.7.1\n```\n\ncheck the file `requirements.txt`. For developers, you should install `requirements_dev.txt`.\n\n### Installation\n\nAMCESS is a **Python 3.9** package\n\n1. Install virtual environment:\n\n `python -m venv <VirtualEnvName>`\n\n2. Activate virtual environment:\n\n `source <VirtualEnvName>`/bin/activate`\n\n3. Install the packages:\n\n 1. after cloning this repository\n\n `pip install .`\n\n 2. or directly from PyPI\n\n `pip install amcess`\n\n4. Run AMCESS (check some examples below). Additionally, you can install `requirements.txt` to use Jupyter notebooks.\n\nFor developers,\n\n1. install dependencies:\n\n `pip install -r requirements.txt -r requirements_dev.txt`\n\n2. Run all test:\n\n `tox`\n\n### Usage\n\nA detailed workflow is provided in the `workflow` directory. It has a list of Jupyter notebooks with detailed examples of AMCESS tools and capabilities.\n\nWorkflow ([Binder](https://mybinder.org/v2/gl/ADanianZE%2Famcess/main?labpath=https%3A%2F%2Fgitlab.com%2FADanianZE%2Famcess%2F-%2Ftree%2Fmain%2Fworkflow)):\n\n1. Getting started with atoms and molecules properties.\n - `01_importing_atoms_and_molecules.ipynb`\n2. Translating and rotating atoms and molecules.\n - `02_move_rotate_molecules.ipynb`\n3. Moving Molecules randomly from a Cluster.\n - `03_move_rotate_cluster.ipynb`\n4. Freezing any molecule and redefining its sphere center.\n - `04_freeze_molecule_redefine_center.ipynb`\n5. Initialize a cluster avoiding atomic overlapping\n - `05_initialize_cluster_and_move_molecule.ipynb`\n\n## Roadmap\n\nSome of the ideas to keep growing are:\n\n- Integration with **RDKit** (multiple format input)\n- Results: geometrical analysis (clustering, k-nearest, k-means, etc.)\n\n## Contributing\n\nThe easiest way to get help with the project is to join the #amcess\nchannel on Discord.\n\nWe hang out there and you can get real-time help with your projects.\n\n- GitHub: https://github.com/e-florez/amcess/issues\n\n- Discord: https://discord.gg/vxQQCjpg\n\n### License\n\nGNU General Public License v3 (GLPv3)\n\n### Authors and Acknowledgment\n\nMain authors: Alejandra Mendez, Juan Jose Aucar, Daniel Bajac, C\u00e9sar Ibarg\u00fcen, Andy Zapata, Edison Florez (_edisonffh@mail.com_)\n\n### Project Status\n\nUnder development\n\n---\n\n## ASCEC (FORTRAN 77 version)\n\nA previous version of AMCESS, called ASCEC [[1]](#1) (Spanish acronym\nAnnealing Simulado con Energ\u00eda Cu\u00e1ntica) was written in FORTRAN77 and\nwas successfully used in a wide range of research and academic applications.\nFrom atomic cluster to molecular cluster, the ASCEC package has produced\nnovel results (structure never seen before) published in the literature. Read more on [ASCEC publications](https://scholar.google.com/scholar?start=0&q=%22ascec%22,+annealing&hl=en&as_sdt=0,5).\n\nYou could check the directory [ASCECV3](https://gitlab.com/ADanianZE/ascec/-/tree/main/ASCECV3)\n\n```\nASCECV3/\n|---papers/\n|---p_ascec/\n|---examples/\n |---adf\n |---dalton\n |---g03\n |---gamess\n |---nwchem\n```\n\n### References\n\n<div style=font-size:12px>\n <a id=\"1\">[1]</a>\n J P\u00e9rez and A Restrepo. Ascec v\u201302: annealing simulado con energ\u00eda cu\u00e1ntica. Property, development and implementation: Grupo de Qu\u00edmica\u2013F\u00edsica Te\u00f3rica, Instituto de Qu\u00edmica, Universidad de Antioquia: Medell\u00edn, Colombia, 2008.\n<br>\n</div>\n",
"bugtrack_url": null,
"license": "The GPLv3 License",
"summary": "Atomic and Molecular Cluster Energy Surface Sampler",
"version": "0.1.2a20",
"project_urls": {
"Homepage": "https://gitlab.com/ADanianZE/amcess"
},
"split_keywords": [
"atomic cluster",
" molecular cluster",
" optimization",
" potential energy surface",
" pes",
" monte carlo",
" simulated annealing",
" bayesian optimization"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8f4b548c8e6187ca63f292dd72e1152c4e75448bc87321c061d099dd6cfad24a",
"md5": "4ced17a71976fa8ffd7e7446da994f3f",
"sha256": "576d05ca9a541c67a24bbd634c539ea81305e7b7e476b02a653ad77c5d4829c8"
},
"downloads": -1,
"filename": "amcess2024-0.1.2a20-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4ced17a71976fa8ffd7e7446da994f3f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 37828,
"upload_time": "2024-03-29T03:24:33",
"upload_time_iso_8601": "2024-03-29T03:24:33.466138Z",
"url": "https://files.pythonhosted.org/packages/8f/4b/548c8e6187ca63f292dd72e1152c4e75448bc87321c061d099dd6cfad24a/amcess2024-0.1.2a20-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "baa15c2bdb8e4733a1f048b326fd0e45c02817397fbd12019449b93112f2ebe1",
"md5": "0517b14b75d6e665c4c70662da3d7464",
"sha256": "9b815f39c0eef92c422630dcda11791d23a1e401c32af9818609ca505872597b"
},
"downloads": -1,
"filename": "amcess2024-0.1.2a20.tar.gz",
"has_sig": false,
"md5_digest": "0517b14b75d6e665c4c70662da3d7464",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 40225,
"upload_time": "2024-03-29T03:24:35",
"upload_time_iso_8601": "2024-03-29T03:24:35.411723Z",
"url": "https://files.pythonhosted.org/packages/ba/a1/5c2bdb8e4733a1f048b326fd0e45c02817397fbd12019449b93112f2ebe1/amcess2024-0.1.2a20.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 03:24:35",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ADanianZE",
"gitlab_project": "amcess",
"lcname": "amcess2024"
}
JSON