BBO-Rietveld

Implementation of BBO-Rietveld, automated crystal structure analysis method based on blackbox optimisation.

Citation

Ozaki, Y., Suzuki, Y., Hawai, T., Saito, K., Onishi, M., and Ono, K.
Automated crystal structure analysis based on blackbox optimisation.
npj Computational Materials 6, 75 (2020).
https://doi.org/10.1038/s41524-020-0330-9

Requirements

Docker
- If you are new to Docker, please setup Docker Desktop for your computer first.
- Here are the documents for Windows and Mac:
  - https://docs.docker.com/docker-for-windows/
  - https://docs.docker.com/docker-for-mac/
- We have verified our software works on macOS(10.14) and Ubuntu(18.04). We recommend macOS or Ubuntu to run this software, but it should work on any computer that Docker running.

Usage

Note: We suppose you are using macOS or Ubuntu and can run docker command without sudo permissions. If you are using Windows, we strongly recommend using WSL2 terminal instead of Command prompt or Windows PowerShell with regard to compatibility.

First, clone this repository to your computer.
Pull bbo-rietveld docker image on terminal.

docker pull resnant/bbo-rietveld:v1.1

If needed, you can build bbo-rietveld docker image from Dockerfile on your computer.

# Please make sure run following command in this directory
docker build ./docker -t bbo-rietveld

In recent versions of GSAS, conda may not be able to resolve the dependencies and GSAS installation may fail.
https://subversion.xray.aps.anl.gov/trac/pyGSAS/wiki/InstallConda

To use your own docker image, you need to specify your docker image in run.sh. Please refer to run.sh.

Run bbo-rietveld container.

./run.sh

docker run --rm -it -p 8888:8888 -v $PWD:/workspace bbo-rietveld:v1 bash
jupyter lab --allow-root --ip 0.0.0.0

Open http://127.0.0.1:8888/?token={TOKEN} in your browser, and you can see a window of JupyterLab. The token will be displayed on your terminal like this:

...

[I 11:23:41.325 LabApp] The Jupyter Notebook is running at:
[I 11:23:41.325 LabApp] http://900cc3c9314c:8888/?token=126c79b021d40344592d5b066225b32474487cb69f711ffe
[I 11:23:41.325 LabApp]  or http://127.0.0.1:8888/?token=126c79b021d40344592d5b066225b32474487cb69f711ffe

...

In this case, you should open http://127.0.0.1:8888/?token=126c79b021d40344592d5b066225b32474487cb69f711ffe.

Then, open 1_Y2O3.ipynb or other notebooks on JupyterLab and run notebook cells.

For expert users

If you are already familiar with Python, you can open notebooks (*.ipynb files) directly in your environment and run it. It requires following packages:

GSAS
Optuna(newer than 3.5)
Jupyter Lab or Jupyter Notebook
Pandas
matplotlib

In the notebook, you should set DATA_DIR and WORK_DIR appropriately for your directory.

Trouble shooting

If you have any problems or questions, please open an issue on GitHub or contact Yuta Suzuki (resnant [at] outlook.jp) by email. Whenever possible, please ask your question via an issue rather than an email. This will help others who encounter similar problems.

FAQ

If port 8888 occupied by other services, following error occurs when you start run.sh:

Error starting userland proxy: listen tcp 0.0.0.0:8888: bind: address already in use.
- Please open run.sh with a texteditor and modify port binding setting to other port, 18888, for example:

docker run --rm -v ${SCRIPT_DIR}/:/bbo_rietveld -p 18888:8888 -it bbo-rietveld

Then, Open http://127.0.0.1:18888/?token={TOKEN} in your browser to open Jupyter Notebook.
If you encounter Unable to find image 'resnant/bbo-rietveld:v1.0' locally error when you run run.sh:
- Please run docker image list on your terminal and make sure that there is resnant/bbo-rietveld on REPOSITORY like following.

resnant@cosmos:~$ docker image list
REPOSITORY              TAG                             IMAGE ID            CREATED             SIZE
resnant/bbo-rietveld    v1.1                            ab342a0ba172        1 months ago        5.24GB

Licence

This software is distributed under Apache 2.0 licence for research and education purposes. If you want to use this code for a commercial purpose, please contact the corresponding author.

The diffraction and crystal structure dataset in data/ directory is distributed under its original licences. See README of the dataset for details.

quantumbeam / BBO-Rietveld