2.Installation¶

In this part, we introduce how DeepH-pack and related packages could be installed.

• DeepH-dock: An integration of versatile tools, such as structure search/generation, data interfaces and post-processing tools.
• DeepH-pack: The main program containing the neural network modules, graph builder, and training/inference functions.

NOTE:

• In the tutorial, we use a re-constructed DeepH-pack version to be released, which is mush faster and powerful.
• The installation of ab initio calculation programs is not included in this tutorial. It is assumed that the readers are able to perform these calculations by themselves.

2.1. Install UV: a python environment manager written by rust¶

Begin by configuring uv environment, a fast and versatile python package manager. Refer to the website of uv for the installation.

On Linux or macOS, you can install uv with a single command (requires an internet connection):

curl -LsSf https://astral.sh/uv/install.sh | sh

It is highly recommended that configuring high-performance mirrors based on your IP location. For example, for users in China, you cloud using the mirror provided by TUNA

# Add the following lines into ~/.config/uv/uv.toml
[[index]]
url = "https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple/"
default = true

2.2. Create deeph python virtual environment with UV¶

Create python 3.13 environments with uv:

mkdir ~/.uvenv
cd ~/.uvenv
uv venv deeph --python=3.13 # It will create the `deeph` venv in current dir

NOTE: Practically, the DFT calculations are usually performed on CPU clusters, and the neural network training/inference is performed on GPU clusters. Therefore, please choose the appropriate location of the environments according to your own situation.

Then, the uv virtual enviornment can be activate with command,

source ~/.uvenv/deeph/bin/activate

Additionally, for users accustomed to conda workflows, we've designed intuitive interactive commands for managing uv environments. The relevant commands are available below:

# Add the following lines into ~/.bashrc or whatever your shell's rc file.
uv-act() {
  local uv_source_path
  if [ $# -eq 0 ]; then
    # Get all envs for uv
    local envs=($(/bin/ls -1 ${HOME}/.uvenv))

    if [ ${#envs[@]} -eq 0 ]; then
      echo "No available environments found in ~/.uvenv"
      return 1
    fi

    # Show the envs
    echo -e "\033[0;36mAvailable environments:\033[0m"
    echo -e "\033[0;36m------------------------------------\033[0m"
    for i in "${!envs[@]}"; do
      printf "\033[1;33m%2d) %s\033[0m\n" "$((i+1))" "${envs[$i]}"
    done
    echo -e "\033[0;36m------------------------------------\033[0m"

    # Get the user choice
    local choice
    printf "\033[0;36mSelect environment (1-${#envs[@]}):\033[0m"
    read -p " " choice

    # Validate the choice
    if [[ ! "$choice" =~ ^[0-9]+$ ]] ||
       [ "$choice" -lt 1 ] ||
       [ "$choice" -gt "${#envs[@]}" ]; then
      echo "Invalid selection" >&2
      return 1
    fi

    # Aativate the env
    uv_source_path="${HOME}/.uvenv/${envs[$((choice-1))]}/bin/activate"
  else
    uv_source_path="${HOME}/.uvenv/$1/bin/activate"
  fi
  echo source ${uv_source_path}
  source ${uv_source_path}
}

uv-new() {
    # Verify arguments
    if [ $# -ne 2 ]; then
        echo "Error: Requires 2 arguments: <environment_name> <python_version>" >&2
        return 1
    fi

    local env_name="$1"
    local python_version="$2"
    local env_dir="${HOME}/.uvenv/${env_name}"

    # Check if environment exists
    if [ -d "$env_dir" ]; then
        echo "Error: Environment '$env_name' already exists" >&2
        return 1
    fi

    # Create environment
    uv venv "$env_dir" --python="${python_version}" || {
        echo "Error: Failed to create environment" >&2
        return 1
    }
}

After adding those lines into ~/.bashrc and source it, you can directly create new deeph uv virtual environment with,

uv-new deeph 3.13 # name, python version

and activate deeph environment with,

uv-act # <- type [enter]
> Available environments:
> ------------------------------------
>  1) deeph
> ------------------------------------
> Select environment (1-1): 1 # <- type '1' and [enter]

2.3. Install DeepH-dock¶

Ensure you've activated the uv environment as described in the previous section, and that you're currently in the deeph environment you created.

For example, run the following command to verify your environment:

which python

Execute this single command to automatically install DeepH-dock and all its dependencies:

uv pip install ./deepx_dock-1.0.0-py3-none-any.whl

NOTE:

• The deepx_dock-1.0.0-py3-none-any.whl file is a pre-provided wheel package.
• DeepH-dock can be run under both CPU and GPU devices.
• During the installation process, an internet connection is required.

2.4. Install DeepH-pack¶

Ensure you've activated the uv environment as described in the previous section, and that you're currently in the deeph environment you created.

uv pip install ./deepx-1.0.6+light-py3-none-any.whl[gpu] --extra-index-url https://download.pytorch.org/whl/cpu

This will install all the dependencies, including GPU version of jax, flax, etc. For CPU-only platforms, replace [gpu] with [cpu].

NOTE:

• The ./deepx-1.0.6+light-py3-none-any.whl file is a pre-provided wheel package.
• The --extra-index-url defines the download url of pytorch. The url ended with "cpu" because pytorch is ony used on the CPU side.
• Please do not confuse the DeepH-pack in this tutorial with the other open-sourced DeepH packages. All the packages provided with this tutorial are named after deepx. It is short for deeph-jax and prevents user confusion between this brand-new JAX-based public release version and previously developed experimental programs (such as DeepH-E3), whose packages are named deeph, upon future releases.