Python

Last updated: October 17, 2026

Python

CrySPY 1.5.0 or Later

• Python >= 3.10
  • PyXtal (>= 1.0.7)
  • (optional) mpi4py
  • (optional, required if algo is BO) PHYSBO
  • (optional, required if algo is BO) dscribe
  • (optional) nglview

Installing csp-cryspy with pip automatically installs required libraries such as PyXtal, pymatgen, and ASE. See Installation > CrySPY 1.3.0 or Later for details.

CrySPY 1.3.0 – 1.4.3

• Python >= 3.9
  • PyXtal (>= 0.5.3)
  • (optional) mpi4py
  • (optional, required if algo is BO) PHYSBO (Not COMBO)
  • (optional, required if algo is BO) dscribe
  • (optional) nglview

If you install csp-cryspy with pip, necessary libraries such as PyXtal, pymatgen, and ASE will be installed automatically. Go to Installation > CrySPY for detail.

2025 June 17, Tested and confirmed to work in the following environments (as installed via pip install csp-cryspy)

• python 3.13.5
• CrySPY 1.4.0
• numpy 1.26.4 (with physbo) and 2.3.0（without physbo. physbo requires numpy < 2.0）
• pandas 2.3.0
• pymatgen 2025.6.14
• pyxtal 1.0.9
• scipy 1.15.3

Quick Install

pip install csp-cryspy

When using BO

pip install dscribe physbo

CrySPY 1.1.0 – 1.2.5

• Python >= 3.8
  • PyXtal (>= 0.5.3)
  • (optional) mpi4py
  • (optional, required if algo is BO) COMBO

If you install csp-cryspy with pip, necessary libraries such as PyXtal will be installed automatically. Go to Installation > CrySPY. Manual installation of COMBO is required when using Bayesian optimization.

CrySPY 1.0.0

• Python >= 3.8
  • PyXtal (>= 0.5.3)
  • (optional, required if algo is BO) COMBO

CrySPY 0.10.0 – 0.10.3

Tested with Homebrew Python 3.8.x and 3.9.x on Mac and Python 3.8.x on Linux.

• Python 3.x.x
  • COMBO
  • PyXtal (>= 0.2.2)
  • (PyXtal requires pymatgen) pymatgen (>= 2022.x.x)

CrySPY 0.9.2

Tested with Homebrew Python 3.8.x and 3.9.x on Mac and Python 3.8.x on Linux.

• Python 3.x.x
  • COMBO
  • pymatgen (>= 2022.x.x)
  • PyXtal (>= 0.2.2)

CrySPY 0.9.0 – 0.9.1

• Python 3.8.x
  • COMBO
  • pymatgen (<= 2021.x.x)
  • PyXtal 0.1.6 - 0.2.1

CrySPY 0.8.0 or Earlier

See the old document which is included CrySPY itself.

CrySPY 1.3.0 or Later

Last updated: July 9, 2026

CrySPY

pip

pip install csp-cryspy

Please note that the name is csp-cryspy on PyPI, not cryspy. The main command, cryspy, is automatically installed in your PATH. You can check by

which cryspy

From version 1.4.1, several additional subcommand are also installed.

Editable Mode

If you want to modify and use the CrySPY source code, it is convenient to install CrySPY in editable mode using the -e option of pip.

Since the GitHub main branch may contain development code that differs from the official release, download the source archive of the desired release from the release page.

After extracting the archive, run:

pip install -e ./CrySPY-x.x.x

PHYSBO and DScribe (Optional)

If you use Bayesian optimization, PHYSBO and DScribe are required.

pip install physbo dscribe

mpi4py (Optional)

When performing random structure generation with MPI parallelization, mpi4py is required.

pip install mpi4py

Jupyter and nglview (Optional)

For analysis on a local PC or in interactive mode, Jupyter is required. If you want to visualize crystal structures using nglview in interactive mode, install nglview by pip.

pip install nglview

CrySPY 1.0.0 -- 1.2.5

CrySPY

pip

CrySPY 1.0.0 or later can be installed by pip.

pip install csp-cryspy

The executable script, cryspy, is automatically installed in your PATH. You can check by

which cryspy

Editable Mode

If you want to change the source code of CrySPY, you can use pip’s editable mode (-e option).

git clone https://github.com/Tomoki-YAMASHITA/CrySPY.git
pip install -e ./CrySPY

Instead of git clone, you can download the compressed file from the release page

cal_fingerprint (Optional)

cal_fingerprint is a program to calculate structure descriptors and is required if algo is BO. From CrySPY 1.0.0, the cal_fingerprint program is included in CrySPY utility. See Instllation/CrySPY_utility/Compile cal_fingerprint for compilation.

Put the executable file of cal_fingerprint in your PATH. Or, specify the path of the executable file in cryspy.in as follows:

[BO]
fppath = /xxx/xxx/xxx/cal_fingerprint

Arm64 on MacOS (Without Rosseta 2)

1. Install miniforge3 (We do not know how to install pyshtools with homebrew python.)
2. Install pymatgen, pyshtools by conda (recent versions of pyshtools are available in conda-forge)

conda install pymatgen
conda install pyshtools

3. Install CrySPY

pip3 install csp-cryspy

Structure Optimizer

Structure Optimizer

At least one optimizer is required.

• First-principles calculation
  • VASP
  • QUANTUM ESPRESSO
  • OpenMX (CrySPY 0.9.0 or later)
• Interatomic potential
  • soiap
  • LAMMPS
• Other
  • ASE (CrySPY 1.2.0 or later)

CrySPY 0.10.3 or Earlier

Installation of CrySPY is very simple. Just download it!

Download

You can put the source code of CrySPY in an arbitrary directory. For example, let us put the source code in ~/CrySPY_root/CrySPY-x.x.x (x.x.x means the version). Use git or download the compressed file.

Git

mkdir ~/CrySPY_root
cd ~/CrySPY_root
git clone https://github.com/Tomoki-YAMASHITA/CrySPY.git CrySPY-x.x.x

ZIP or tar.gz File

Download the source as a zip or tar.gz file from GitHub release.
Then put the source like ~/CrySPY_root/CrySPY-x.x.x

Directory Tree

Directory tree in ~/CrySPY_root/CrySPY-x.x.x/:

CrySPY-x.x.x
├── CHANGELOG.md
├── CrySPY/
│   ├── BO/
│   ├── EA/
│   ├── IO/
│   ├── LAQA/
│   ├── RS/
│   ├── __init__.py
│   ├── calc_dscrpt/
│   ├── f-fingerprint/
│   ├── find_wy/
│   ├── gen_struc/
│   ├── interface/
│   ├── job/
│   └── start/
│   └── utility.py
├── LICENSE
├── README.md
├── cryspy.py
├── docs/
├── example/
└── utility/

Setup (Optional)

find_wy (Optional)

When you use find_wy, put the executable file of find_wy in ~/CrySPY_root/CrySPY-x.x.x/CrySPY/find_wy/, so that the executable file path is ~/CrySPY_root/CrySPY-x.x.x/CrySPY/find_wy/find_wy.

cd ~/CrySPY_root/CrySPY-x.x.x/CrySPY/find_wy
cp ~/local/find_wy/find_wy .

Compile cal_fingerprint (Optional)

When you use Bayesian optimization, compile cal_fingerpirnt program which calculates structure descriptors.

cd ~/CrySPY_root/CrySPY-x.x.x/CrySPY/f-fingerprint
emacs Makefile
make

Make sure that the executable file of cal_fingerprint exists in ~/CrySPY_root/CrySPY-x.x.x/CrySPY/f-fingerprint/.

find_wy (Optional)

CrySPY have utilized find_wy to generate a random structure for a given space group (symmetry). However, CrySPY employs PyXtal library for structure generation as default since version 0.9.0. You can skip to install find_wy in CrySPY 0.9.0 or later, but you may use find_wy. For CrySPY 0.8.x or earlier, find_wy is required to generate a random structure for a given space group.

Installation of find_wy

m_tspace

First you need compile m_tspace for find_wy. Check these sites to compile it.

• m_tspace
• Wiki of m_tspace

Download the source code of m_tspace in an arbitrary directory. For example:

$ mkdir -p ~/local
$ cd ~/local
$ git clone https://github.com/nim-hrkn/m_tspace.git

Additional two files are required to compile m_tspace. Download the following files in ~/local/m_tspace from TSPASE:

• tsp98.f
• prmtsp.f

$ cd m_tspace
$ wget http://phoenix.mp.es.osaka-u.ac.jp/~tspace/tspace_main/tsp07/tsp98.f
$ wget http://phoenix.mp.es.osaka-u.ac.jp/~tspace/tspace_main/tsp07/prmtsp.f

Edit the makefile and run the make command. If you use ifort, you had better delete -check all option and use -O2 option.

$ emacs makefile
$ head -n 4 makefile
#FC=gfortran
#FFLAGS=-g -cpp -DUSE_GEN -ffixed-line-length-255
FC=ifort
FFLAGS=-O2 -g -traceback -cpp -DUSE_GEN -132
$ make

If you used gfortran, you might face the following problem:

tsp98.f:9839:32:

       CALL SUBGRP(MG,JG,MGT,JGT,NTAB,IND)
                                1
Error: Actual argument contains too few elements for dummy argument 'ntab' (12/48) at (1)
make: *** [tsp98.o] Error 1

Then change the source file of tsp98.f like this (line 9925):

Before:

9913: C SUBROUTINE SUBGRP ====*====3====*====4====*====5====*====6====*====7
9914: C
9915: C    IF (JG(I),I=1,MG) IS A SUBGROUP OF (JGT(J),J=1,MGT) THEN
9916: C          TABLE (NTAB(I),I=1,MG) IS MADE HERE AND IND=0
9917: C    ELSE
9918: C          IND=-1
9919: C
9920: C                 1993/12/25
9921: C                   BY  S.TANAKA AND A. YANASE
9922: C---*----1----*----2----*----3----*----4----*----5----*----6----*----7
9923: C
9924:       SUBROUTINE SUBGRP(MG,JG,MGT,JGT,NTAB,IND)
9925:       DIMENSION NTAB(48),JG(48),JGT(48)

After:

9913: C SUBROUTINE SUBGRP ====*====3====*====4====*====5====*====6====*====7
9914: C
9915: C    IF (JG(I),I=1,MG) IS A SUBGROUP OF (JGT(J),J=1,MGT) THEN
9916: C          TABLE (NTAB(I),I=1,MG) IS MADE HERE AND IND=0
9917: C    ELSE
9918: C          IND=-1
9919: C
9920: C                 1993/12/25
9921: C                   BY  S.TANAKA AND A. YANASE
9922: C---*----1----*----2----*----3----*----4----*----5----*----6----*----7
9923: C
9924:       SUBROUTINE SUBGRP(MG,JG,MGT,JGT,NTAB,IND)
9925:       DIMENSION NTAB(12),JG(48),JGT(48)

If you succeed in compiling, you get m_tsp.a.

find_wy

Check these sites to compile find_wy:

• find_wy
• Wiki of find_wy

Download the source code of find_wy in an arbitrary directory. For example:

$ mkdir -p ~/local
$ cd ~/local
$ git clone https://github.com/nim-hrkn/find_wy.git

Edit make.inc and set the path to the m_tsp.a that you just prepared.

$ cd find_wy
$ emacs make.inc
$ head -n 4 make.inc
TSPPATH=~/local/m_tspace
#INCPATH = -I $(TSPPATH)
TSP=$(TSPPATH)/m_tsp.a

You can delete -check all option and use -O2 option. Then run the make command.

$ make

When you get the executable file of find_wy, run the following command for test:

$ ./find_wy input_sample/input_si4o8.txt

If there is no problem, POS_WY_SKEL_ALL.json file is generated.

Executable File of find_wy

CrySPY 1.0.0 or Later

Put the executable file of find_wy in your PATH. Or, specify the path of the executable file in cryspy.in as follows:

[structure]
use_find_wy = True
fwpath = /xxx/xxx/xxx/find_wy

CrySPY 0.10.3 or Earlier

When you use find_wy, put the executable file of find_wy in ~/CrySPY_root/CrySPY-x.x.x/CrySPY/find_wy/, so that the executable file path is ~/CrySPY_root/CrySPY-x.x.x/CrySPY/find_wy/find_wy.

CrySPY Utility (Optional)

Setting up Python environment in your local PC is useful to analyze CrySPY results. Utility tools (jupyter notebook and python scripts) are available for analysis and visualization. Input examples are also included in CrySPY utility.

You need several Python libraries such as

• jupyter
• NumPy
• pandas
• matplotlib
• pymatgen

Download CrySPY Utility

Git

$ git clone https://github.com/Tomoki-YAMASHITA/CrySPY_utility.git

ZIP

Go to CrySPY utility and click green Code button, then choose Download ZIP.