Genarris gnrs is a random molecular crystal structure generator and a computational workflow for molecular crystal structure prediction (CSP).
Clone the repository:
git clone https://github.com/Yi5817/Genarris.git
cd Genarris
git submodule update --init --recursiveCreate and activate the virtual enviornment using your favorite venv tool:
virtualenv -p python3.11 gnrs_env
source gnrs_env/bin/activateInstall mpi4py with the MPI compiler:
MPICC=$(which mpicc) pip install mpi4py==3.1.5Note
On high-performance computing machine, C MPI compiler may differ. Please refer to the mpi4py documentation or contact the system administrator.
pip install -e .Note
mpicc is used to build the C extensions. To use a specific MPI compiler, modify the mpi_compiler variable in the setup.py file.
Genarris supports various energy calculators through the ASE Calculator. These enable energy evaluation and geometry relaxation with machine learning interatomic potentials (MLIPs), force field/semi-empirical methods, and DFT packages.
Tip
You can implement additional calculators under gnrs/energy/.
| Calculator | Type | Install |
|---|---|---|
| UMA | MLIP | pip install -e .[uma] |
| MACE-OFF | MLIP | pip install -e .[mace] |
| AIMNet2 | MLIP | pip install git+https://github.com/isayevlab/aimnetcentral.git |
| DFTB+ | Semi-Empirical | — |
| FHI-aims | DFT | — |
| VASP | DFT | — |
⚠️ To access gated UMA models, you need to get a HuggingFace account and request access to the UMA model repository.
Genarris uses a configuration file to control crystal structure generation and selection.
-
Create a configuration file
ui.confHere's an example with key parameters for
generationandsymm_rigid_presssteps:[master] name = molecule_path = [""] Z = log_level = info [workflow] tasks = ['generation', 'symm_rigid_press'] [generation] num_structures_per_spg = 4000 sr = 0.95 # sr is an alias for specific_radius_proportion max_attempts_per_spg = 100000000 tol = 0.01 unit_cell_volume_mean = predict volume_mult = 1.5 max_attempts_per_volume = 10000000 spg_distribution_type = standard generation_type = crystal natural_cutoff_mult = 1.2 [symm_rigid_press] sr = 0.85 method = BFGS tol = 0.01 natural_cutoff_mult = 1.2 debug_flag = False maxiter = 5000 [experimental_structure] path = ""
-
Prepare your input molecule geometry file (any format supported by
ase.io.read()) -
Run Genarris with MPI parallelization:
mpirun -np <num_processes> gnrs --config <config_file>
For example, to run with 8 processes:
mpirun -np 8 gnrs --config ui.conf
The cases directory contains crystal structure prediction (CSP) results for 6 organic molecules studied in the Genarris 3.0 paper. Each case includes:
- Experimental structures: From the Cambridge Structural Database (CSD)
- Generated structures: CIF files of crystal structures generated by Genarris and relaxed using MACE-OFF23 and PBE+MBD methods
- Analysis data: Total energies from MACE-OFF23 and PBE+MBD methods
If you use Genarris, please cite our papers:
@article{genarrisv3,
author = {Yang, Yi and Tom, Rithwik and Wui, Jose AGL and Moussa, Jonathan E and Marom, Noa},
title = {Genarris 3.0: Generating Close-Packed Molecular Crystal Structures with Rigid Press},
author={Yang, Yi and Tom, Rithwik and Wui, Jose AGL and Moussa, Jonathan E and Marom, Noa},
journal={Journal of Chemical Theory and Computation},
volume = {21},
number = {21},
pages = {11318--11332},
year={2025},
publisher={ACS Publications}
}
@article{genarrisv2,
title={Genarris 2.0: A random structure generator for molecular crystals},
author={Tom, Rithwik and Rose, Timothy and Bier, Imanuel and O’Brien, Harriet and V{\'a}zquez-Mayagoitia, {\'A}lvaro and Marom, Noa},
journal={Computer Physics Communications},
volume={250},
pages={107170},
year={2020},
publisher={Elsevier}
}
@article{genarrisv1,
title={Genarris: Random generation of molecular crystal structures and fast screening with a Harris approximation},
author={Li, Xiayue and Curtis, Farren S and Rose, Timothy and Schober, Christoph and Vazquez-Mayagoitia, Alvaro and Reuter, Karsten and Oberhofer, Harald and Marom, Noa},
journal={The Journal of Chemical Physics},
volume={148},
number={24},
year={2018},
publisher={AIP Publishing}
}
@article{pymove,
title={Machine learned model for solid form volume estimation based on packing-accessible surface and molecular topological fragments},
author={Bier, Imanuel and Marom, Noa},
journal={The Journal of Physical Chemistry A},
volume={124},
number={49},
pages={10330--10345},
year={2020},
publisher={ACS Publications}
}Contributions are welcome! Please feel free to submit a Pull Request.
We would appreciate it if you could share any feedback about performance and improvements.
Genarris is available under the BSD-3-Clause License.
