Installation

XenonPy can be installed using pip in 3.6 and 3.7 on Mac, Linux, and Windows. Alternatively, we recommend using the Docker Image if you have no installation preference. We have no plan to support Python 2.x. One of the main reasons is that the pymatgen library will not support Python 2 from 2019. See this link for details.

Using conda and pip

pip is a package management system for installing and updating Python packages, which comes with any Python distribution. Conda is an open source package management system and environment management system that runs on Windows, macOS, and Linux. Conda easily creates, saves, loads and switches between environments on your local computer.

XenonPy has 3 peer dependencies, which are PyTorch, pymatgen and rdkit. Before you install XenonPy, you have to install them. The easiest way to install all 3 packages is to use Conda. The following official tutorials will guide you through a successful installation.

PyTorch: https://pytorch.org/get-started/locally/
pymatgen: http://pymatgen.org/index.html#getting-pymatgen
rdkit: https://www.rdkit.org/docs/Install.html

For convenience, several environments preset are available at conda_env. You can use these files to create a runnable environment on your local machine.

$ conda create -n <env_name_you_liked> python={3.6 or 3.7}  # use `conda create` command to create a fresh environment with specific name and python version
$ conda env update -n <env_name_you_created> -f <path_to_env_file>  # use `conda env update` command to sync packages with the preset environment

Note

For Unix-like (Linux, Mac, FreeBSD, etc.) system, the above command will be enough. For windows, additional tools are needed. We highly recommend you to install the Visual C++ Build Tools before creating your environment. Also, confirm that you have checked the Windows 10 SDK (assuming the computer is Windows 10) on when installing the build tools.

The following example shows how to create an environment named xenonpy in python3.7 and cuda10.1 supports step-by-step.

Chose an environment preset and download it.

Because we want to have cuda10.1 supports, The cuda101.yml preset will surely satisfy this work. If curl has been installed, the following command will download the environment file to your local machine.
$ curl -O https://raw.githubusercontent.com/yoshida-lab/XenonPy/master/conda_env/cuda101.yml

Create the environment and install packages using environment file.

The following commands will rebuild a python3.7 environment, and install the packages which are listed in cuda101.yml.
$ conda create -n xenonpy python=3.7
$ conda env update -n xenonpy -f cuda101.yml

Enter the environment by name.

In this example, it’s xenonpy.
$ source activate xenonpy

# or

$ activate xenonpy

# or

$ conda activate xenonpy
Note

Which command should be used is based on your system and your conda configuration.

Update XenonPy

When you reached here, XenonPy has been installed successfully. If you want to update your old installation of XenonPy, ssing pip install -U xenonpy.
$ pip install -U xenonpy

Using docker

Docker is a tool designed to easily create, deploy, and run applications across multiple platforms using containers. Containers allow a developer to pack up an application with all of the parts it needs, such as libraries and other dependencies, into a single package. We provide the official docker images via the Docker hub.

Using docker needs you to have a docker installation on your local machine. If you have not installed it yet, follow the official installation tutorial to install docker CE on your machine. Once you have done this, the following command will boot up a jupyterlab for you with XenonPy inside. See here to know what other packages are available.

$ docker run --rm -it -v $HOME/.xenonpy:/home/user/.xenonpy -v <path/to/your/work_space>:/workspace -p 8888:8888 yoshidalab/xenonpy

If you have a GPU server/PC running Linux and want to bring the GPU acceleration to docker. Just adding --runtime=nvidia to docker run command.

$ docker run --runtime=nvidia --rm -it -v $HOME/.xenonpy:/home/user/.xenonpy -v <path/to/your/work_space>:/workspace -p 8888:8888 yoshidalab/xenonpy

For more information about using GPU acceleration in docker, see nvidia docker. .. note:

If you get **docker: Error response from daemon: Unknown runtime specified nvidia.** when runing docker with ``--runtime=nvidia``.
Please update your ``nvidia-docker`` to ``nvidia-docker2`` and repleace ``--runtime=nvidia`` with ``--gpus all``.
see `this issue <https://github.com/NVIDIA/nvidia-docker/issues/838>`_ for details.

Permission failed

You may have a permission problem when you try to open/save jupyter files. This is because docker is a container system running like a virtual machine. Files will have different permission when be mounted onto a docker container. The simplest way to resolve this problem is changing the permission of failed files. You can open a terminal in jupyter notebook and type:

$ sudo chmod 666 permission_failed_file

This will change file permission to r+w for all users.

Installing in development mode

The user who plans to contribute to XenonPy has to extend the python environment to support pytest and other development tools. The simplest way to extend your environment is using extra_env.yml.

$ git clone https://github.com/yoshida-lab/XenonPy.git

under the cloned folder, run the following to install XenonPy in development mode:

$ cd XenonPy
$ conda env update -n <your_env_name> -f devtools/extra_env.yml
$ pip install -e .

Troubleshooting/issues

Contact us at issues and Gitter when you have trouble.

Please provide detailed information (system specification, Python version, and input/output log, and so on).