mosaics

Evolutionary Monte Carlo algorithm for optimization in chemical space.

📋 Description

MOSAiCS is an Evolutionary Monte Carlo algorithm designed for optimizing target functions over the space of organic molecules. The algorithm combines the benefits of both genetic algorithms and Monte Carlo techniques, providing a powerful tool for complex optimization tasks in applied science.

For more information, please read our paper "Evolutionary Monte Carlo of QM properties in chemical space: Electrolyte design" published on arXiv.

📦 Dependencies

MOSAiCS has the following dependencies:

• numpy
• igraph
• sortedcontainers
• scipy
• loky
• joblib

Additional packages are required to run some example scripts.

🔧 Installation

1. Clone the repository:

   git clone https://github.com/chemspacelab/mosaics

2. Change into the mosaics directory:

   cd mosaics

3. Install the package using Makefile (which in turn uses setuptools)

   make install

   or pip

   pip install .

🧰 Usage

To use the package in your Python script import it with:

import mosaics

💻 Examples

We have prepared several examples to help you get started with MOSAiCS. Each example is located in its own directory under the examples/ folder.

Toy Minimization

This example shows the basics of the our algorithm by using it to minimize a function of chemical graph's nuclear charges over chemical space.

xTB Property Optimization

Optimize solvation energy using extended Tight-Binding (xTB) calculations with MMFF94 conformers. (Largely a reproduction of the numerical experiments performed in arXiv:2307.15563.) NOTE: Requires installation of morfeus and xtb-python packages.

Distributed Random Walk

Learn to distribute computational work across multiple nodes or processors.

Blind Optimization Protocol

Learn to use protocols for tuning beta parameters during optimization.

ChemSpaceSampler

Showcases the algorithm's ability to explore various regions of the chemical space. For further reading see "Understanding Representations by Exploring Galaxies in Chemical Space" published on arXiv.

🤝 Contributing

We welcome contributions and feedback from the community. If you encounter any issues or have suggestions for improvements, please open an issue on GitHub.

📏 Tests

Unfortunately, due to uncertain nature of Monte Carlo trajectories the only way to completely verify correctness of installation is by running a relatively long Monte Carlo calculation with a certain random number generator seed and compare it to the benchmark trajectory. Hence each example script in examples with a toy problem function also has a test version in tests that compares code output to a benchmark; the calculation takes significantly more time than a typical test. A reference environment for which the benchmarks could be reproduced is found in tests/benchmark_env.yml (in case, for example, an environment update changes the way random number generation works). Passing the test in tests/01_toy_minimization should be enough to verify installation.

📜 License

This project is licensed under the MIT License

📧 Support

For support or questions related to the MOSAiCS codebase, please contact the authors.