Genarris

Genarris gnrs is a random molecular crystal structure generator and a computational workflow for molecular crystal structure prediction (CSP).

Installation

Clone the repository:

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

Create and activate the virtual enviornment using your favorite venv tool:

virtualenv -p python3.11 gnrs_env
source gnrs_env/bin/activate

Install Build Dependencies

Install build dependencies, PyTorch, and mpi4py with the correct MPI compiler before installing the package:

pip install "setuptools>=61.0" "setuptools-scm>=8" wheel "swig>=4.1,<4.3" Cython "numpy>=2.0,<2.3"
pip install torch==2.8.0 --index-url https://download.pytorch.org/whl/cu129
MPICC=$(which mpicc) pip install mpi4py --no-binary mpi4py

Note

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

Install gnrs using pip

pip install -e . --no-build-isolation

Note

mpicc is used to build the C extensions. To use a specific MPI compiler, modify the MPICC variable in setup.py.

rigid_press extension links against BLAS and LAPACK (-llapack -lblas by default). On HPC systems where library names differ (e.g., TACC Vista), edit the libraries and library_dirs fields of the rigid_press extension in setup.py.

See the installation guide for more details.

Optional Energy Calculators

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.

Quick Start

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

Basic Workflow

1. Create a configuration file ui.conf

   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
   max_attempts_per_spg        = 100000000
   tol                         = 0.01
   ucv_mean                    = predict
   ucv_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 to the experimental structure file if known
   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

Citation

If you use Genarris, please cite:

Yang, Y., Tom, R., Wui, J. A., Moussa, J. E., & Marom, N. Genarris 3.0: Generating Close-Packed Molecular Crystal Structures with Rigid Press. J. Chem. Theory Comput., 21, 11318–11332 (2025).

@article{genarrisv3,
  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   = {J. Chem. Theory Comput.},
  volume    = {21},
  number    = {21},
  pages     = {11318--11332},
  year      = {2025},
  publisher = {ACS Publications}
}

For the full list of related papers, see the Citation page.

Applications

Genarris has been applied to a wide range of molecular crystal studies:

Project	Description	Links
FastCSP	Accelerated Molecular Crystal Structure Prediction with Universal Model for Atoms
OMC25	Open Molecular Crystals 2025 — 27M+ molecular crystal structures for training ML interatomic potentials

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.