Skip to content


MAGUS: Machine learning And Graph theory assisted Universal structure Searcher


MAGUS is a machine learning and graph theory assisted crystal structure prediction method developed by Prof. Jian Sun's group at the School of Physics at Nanjing University. The programming languages are mainly Python and C++ and it is built as a pip installable package. Users can use just a few commands to install the package. MAGUS has also the advantage of high modularity and extensibility. All source codes are transparent to users after installation, and users can modify particular parts according to their needs.

MAGUS has been used to study many systems. Several designed new materials have been synthesized experimentally, and a number of high-profile academic papers have been published. (Publications using MAGUS)

Current Features

  • Generation of atomic structures for a given symmetry, support cluster, surface, 2D and 3D crystals including molecules, confined systems, etc;
  • Geometry optimization of a large number of structures with DFT or active learning machine learning potential;
  • Multi-target search for structures with fixed or variationally component;
  • API for VASP, CASTEP, Quantum ESPRESSO, ORCA, MTP, NEP, DeepMD, gulp, lammps, XTB, ASE, etc. Easy for extension.


An overview of code documentation and tutorials for getting started with MAGUS can be found here.

How to get access

MAGUS is free for non-commercial academic use. To get access to the source code, you need to register at the following link ( ). We will invite you into our gitlab project as soon as possible. Then you can see the whole project after logging in. Please contact us by email ( if you have any questions concerning MAGUS.

How to cite

Reference cite for what
[1, 2] for any work that used MAGUS
[3, 4] Graph theory
[5] Surface reconstruction
[6] Structure searching in confined space
  1. Junjie Wang, Hao Gao, Yu Han, Chi Ding, Shuning Pan, Yong Wang, Qiuhan Jia, Hui-Tian Wang, Dingyu Xing, and Jian Sun, “MAGUS: machine learning and graph theory assisted universal structure searcher”, Natl. Sci. Rev. 10, nwad128, (2023). (

  2. Kang Xia, Hao Gao, Cong Liu, Jianan Yuan, Jian Sun, Hui-Tian Wang, Dingyu Xing, “A novel superhard tungsten nitride predicted by machine-learning accelerated crystal structure search”, Sci. Bull. 63, 817 (2018). (

  3. Hao Gao, Junjie Wang, Yu Han, Jian Sun, “Enhancing Crystal Structure Prediction by Decomposition and Evolution Schemes Based on Graph Theory”, Fundamental Research 1, 466 (2021). (

  4. Hao Gao, Junjie Wang, Zhaopeng Guo, Jian Sun, “Determining dimensionalities and multiplicities of crystal nets” npj Comput. Mater. 6, 143 (2020). (

  5. Yu Han, Junjie Wang, Chi Ding, Hao Gao, Shuning Pan, Qiuhan Jia, and Jian Sun, “Prediction of surface reconstructions using MAGUS”, J. Chem. Phys. 158, 174109 (2023). (

  6. Chi Ding, Junjie Wang, Yu Han, Jianan Yuan, Hao Gao, and Jian Sun, “High Energy Density Polymeric Nitrogen Nanotubes inside Carbon Nanotubes”, Chin. Phys. Lett. 39, 036101 (2022). (Express Letter) (

Publications using MAGUS

see publication list