Genarris

Genarris gnrs is a random molecular crystal structure generator.

Installation

Prerequisites

• Python 3.8+
• C Compiler with MPI support

Environment Setup

1. Clone the repository:

   git clone https://github.com/Yi5817/Genarris.git
   cd Genarris
   git submodule update --init --recursive

2. Create and activate the conda environment:

   conda create -n gnrs_env python=3.11
   conda activate gnrs_env

Install MPI Support

Install mpi4py with the MPI compiler:

MPICC=$(which mpicc) pip install mpi4py==3.1.5

Note: On high-performance computing machine, C MPI compiler may differ. Please refer to the mpi4py documentation or contact the system administrator.

Install gnrs

pip install .

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.

Optional Energy Calculators

Note: Users are welcome to implement additional calculators under gnrs/energy/

• MACE-OFF - Machine learning interatomic potential
• FHI-aims - All-electron DFT code (ASE docs)
• VASP - Plane-wave DFT package (ASE docs)
• DFTB+ - Density functional tight binding (ASE docs)

Usage

Genarris uses a configuration file to control crystal structure generation and selection.

Basic Workflow

1. Create a configuration file

   Here's an example with key parameters for generation and symm_rigid_press steps:

   [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 = ""

2. Prepare your input molecule geometry file (any format supported by ase.io.read())

3. 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

Case Studies

The cases directory contains crystal structure prediction (CSP) results for 6 organic molecules studied in the Genarris 3.0 paper. Each case includes:

• Generated structures: CIF files of crystal structures generated by Genarris and relaxed using MACE-OFF23 and PBE+MBD methods
• Experimental structures: From CSD
• Analysis data: Relative lattice energies from MACE-OFF23 and PBE+MBD methods

For detailed results and analysis, see the individual case directories:

• Aspirin
• ε-CL-20
• 2,4-DNI
• δ-HMX
• Target I
• Target XXII

Citation

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},
    journal = {ChemRxiv},
    year = {2025},
    url = {https://doi.org/10.26434/chemrxiv-2025-046zn},
    doi = {10.26434/chemrxiv-2025-046zn}
}

@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}
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Feedback and Support

We would appreciate it if you could share any feedback about performance and improvements.

LICENSE

Genarris is available under the BSD-3-Clause License.