README.md

# BOMLIP-CSP

An open-source Python framework that integrates machine learning interatomic 
potentials (MLIPs) with a tailored batched optimization strategy, enabling rapid, 
unbiased structure prediction across the full density range


## Install the BOMLIP-CSP
```sh
git clone https://github.com/pic-ai-robotic-chemistry/BOMLIP-CSP.git --recursive
conda create -n BOMLIP_CSP python=3.10 -y
conda activate BOMLIP_CSP
cd BOMLIP-CSP/batchASE
# using chmod -R 755 in your BOMLIP-CSP folder if you do not have exection permission
./reproduce/init_mace.sh
source util/env.sh
cd ..
```

## Perform a complete CSP process

Starting the exclusive mode to further accelerate the process if you have administrator privileges.
```sh
sudo ./util/mps_start.sh
```

The main program of the CSP process.

BATCHED GEOMETRY OPTIMIZATION REQUIRES GPU USAGE!
PLEASE CONFIRM THE GPU AND WORKER SETTINGS IN THE SHELL SCRIPT BEFORE RUNNING THIS COMMAND!
which includes --gpu_offset --n_gpus --num_workers.
```sh
./csp.sh
```

End the exclusive mode after running.
```sh
sudo ./util/mps_clean.sh
```

## Perform conformer search / structure generation / structure optimization separately
### conformer search
In csp.sh, the argument --mode controls the jobs to do.

Use conformer_only to perform conformer search task only.
```sh
python "${TOP_DIR}/main.py" --path ${TAR_DIR} --smiles "C1CC2=COC=C12" \
     --num_generation 100 --generate_conformers 10 --mode conformer_only > generate_conformer.log 2>&1
```
### structure generation
Or use structure_only to perform structure generation only.
In this mode, conformers (generated by this program or provided by yourself as .xyz file from other methods) should be provided in folder ${TAR_DIR}/molecule_${i}/conformers as conformer_${j}.xyz files
where i start from 1 and j start from 0.
```sh
python "${TOP_DIR}/main.py" --path ${TAR_DIR} --molecule_num_in_cell 1 \
     --space_group_list 14,61 --add_name XULDUD --max_workers 16 --num_generation 100 \
     --use_conformers 4 --mode structure_only > generate_structure.log 2>&1
```
Conformer search and structure generation could also be done in python script with higher freedom (e.g. higher Z', higher-order co-crystal or control trail structure number for each space group), see structure_generate.py.

### structure optimization
Structure optimization is done by a seperate command
```sh
python "${TOP_DIR}/batchASE/scripts/opt_batch.py" ...
```

Explanations for all arguments are provided in main.py and batchASE/scripts/opt_batch.py.


### If you want to configure the 7net environment.

```sh
#!/bin/bash
conda create -n 7net-cueq python=3.10 -y && conda activate 7net-cueq
cd BOMLIP-CSP/batchASE
./reproduce/init_7net.sh && source util/env.sh
```

The optimization command for 7net is given in csp.sh
```sh
# Use a fixed batch size for structural optimization
python "${TOP_DIR}/batchASE/scripts/opt_batch.py" --target_folder "${TAR_DIR}/structures" \
    --molecule_single 13 --gpu_offset 0 --n_gpus 8 --num_workers 48 --batch_size 2 \
    --max_steps 3000 --filter1 UnitCellFilter --filter2 UnitCellFilter \
    --optimizer1 BFGSFusedLS --optimizer2 BFGS --num_threads 2 --cueq true \
    --use_ordered_files true --model sevennet > opt.log 2>&1
```

## Method
See the BOMLIP-CSP paper for more details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Third-party Dependencies

This project includes dependencies with various licenses:
- **MACE**: MIT License (compatible)
- **FairChem**: MIT License (compatible)
- **SevenNet**: GPL v3 License (Note: GPL is a copyleft license)

### License Compatibility Notice

**Important**: This project can run completely without relying on SevenNet. 
This project includes SevenNet as an optional dependency, which is licensed under GPL v3.
If you use SevenNet functionality, you should be aware of the GPL licensing requirements.
For commercial use or to avoid GPL restrictions, consider using only the MACE calculator 
functionality.

## Citation

If you use this code in your research, please cite:

```bibtex
@software{BOMLIP_CSP,
  author = {Chengxi Zhao, Zhaojia Ma, Dingrui Fan},
  title = {BOMLIP_CSP: Integrating machine learning interatomic potentials with batched optimization for crystal structure prediction},
  year = {2025},
  url = {https://github.com/pic-ai-robotic-chemistry/BOMLIP-CSP}
}
```