9. Command line interface

DeePMD-kit: A deep learning package for many-body potential energy representation and molecular dynamics

usage: dp [-h] [-b {tensorflow,tf,pytorch,pt} | --tensorflow | --pytorch]
          [--version]
          {transfer,train,freeze,test,compress,doc-train-input,model-devi,convert-from,neighbor-stat,train-nvnmd,gui,convert-backend}
          ...

9.1. Named Arguments

-b, --backend

Possible choices: tensorflow, tf, pytorch, pt

The backend of the model. Default can be set by environment variable DP_BACKEND.

Default: “tensorflow”

--tensorflow, --tf

Alias for –backend tensorflow

--pytorch, --pt

Alias for –backend pytorch

--version

show program’s version number and exit

9.2. Valid subcommands

command: Possible choices: transfer, train, freeze, test, compress, doc-train-input, model-devi, convert-from, neighbor-stat, train-nvnmd, gui, convert-backend

9.3. Sub-commands

9.3.1. transfer

(Supported backend: TensorFlow) pass parameters to another model

dp transfer [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
            [-r RAW_MODEL] [-O OLD_MODEL] [-o OUTPUT]

9.3.1.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-r, --raw-model

the model receiving parameters

Default: “raw_frozen_model.pb”

-O, --old-model

the model providing parameters

Default: “old_frozen_model.pb”

-o, --output

the model after passing parameters

Default: “frozen_model.pb”

9.3.2. train

train a model

dp train [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
         [-m {master,collect,workers}]
         [-i INIT_MODEL | -r RESTART | -f INIT_FRZ_MODEL | -t FINETUNE]
         [-o OUTPUT] [--skip-neighbor-stat] [--model-branch MODEL_BRANCH]
         [--force-load]
         INPUT

9.3.2.1. Positional Arguments

INPUT: the input parameter file in json or yaml format

9.3.2.2. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-m, --mpi-log

Possible choices: master, collect, workers

Set the manner of logging when running with MPI. ‘master’ logs only on main process, ‘collect’ broadcasts logs from workers to master and ‘workers’ means each process will output its own log

Default: “master”

-i, --init-model

Initialize the model by the provided path prefix of checkpoint files.

-r, --restart

Restart the training from the provided path prefix of checkpoint files.

-f, --init-frz-model

Initialize the training from the frozen model.

-t, --finetune

Finetune the frozen pretrained model.

-o, --output

The output file of the parameters used in training.

Default: “out.json”

--skip-neighbor-stat

Skip calculating neighbor statistics. Sel checking, automatic sel, and model compression will be disabled.

Default: False

--model-branch

(Supported backend: PyTorch) Model branch chosen for fine-tuning if multi-task. If not specified, it will re-init the fitting net.

Default: “”

--force-load

(Supported backend: PyTorch) Force load from ckpt, other missing tensors will init from scratch

Default: False

examples:: dp train input.json dp train input.json –restart model.ckpt dp train input.json –init-model model.ckpt

9.3.3. freeze

freeze the model

dp freeze [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
          [-c CHECKPOINT_FOLDER] [-o OUTPUT] [-n NODE_NAMES] [-w NVNMD_WEIGHT]
          [--united-model] [--head HEAD]

9.3.3.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-c, --checkpoint-folder, --checkpoint

Path to checkpoint, either a folder containing checkpoint or the checkpoint prefix

Default: “.”

-o, --output

Filename (prefix) of the output model file. TensorFlow backend: suffix is .pb; PyTorch backend: suffix is .pth

Default: “frozen_model”

-n, --node-names

(Supported backend: TensorFlow) the frozen nodes, if not set, determined from the model type

-w, --nvnmd-weight

(Supported backend: TensorFlow) the name of weight file (.npy), if set, save the model’s weight into the file

--united-model

(Supported backend: TensorFlow) When in multi-task mode, freeze all nodes into one united model

Default: False

--head

(Supported backend: PyTorch) Task head to freeze if in multi-task mode.

examples:: dp freeze dp freeze -o graph.pb

9.3.4. test

test the model

dp test [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH] [-m MODEL]
        [-s SYSTEM | -f DATAFILE] [-S SET_PREFIX] [-n NUMB_TEST]
        [-r RAND_SEED] [--shuffle-test] [-d DETAIL_FILE] [-a]
        [-i INPUT_SCRIPT] [--head HEAD]

9.3.4.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-m, --model

Frozen model file (prefix) to import. TensorFlow backend: suffix is .pb; PyTorch backend: suffix is .pth.

Default: “frozen_model”

-s, --system

The system dir. Recursively detect systems in this directory

Default: “.”

-f, --datafile

The path to file of test list.

-S, --set-prefix

(Supported backend: TensorFlow) The set prefix

Default: “set”

-n, --numb-test

The number of data for test. 0 means all data.

Default: 0

-r, --rand-seed

(Supported backend: TensorFlow) The random seed

--shuffle-test

Shuffle test data

Default: False

-d, --detail-file

The prefix to files where details of energy, force and virial accuracy/accuracy per atom will be written

-a, --atomic

(Supported backend: TensorFlow) Test the accuracy of atomic label, i.e. energy / tensor (dipole, polar)

Default: False

-i, --input_script

(Supported backend: PyTorch) The input script of the model

--head

(Supported backend: PyTorch) Task head to test if in multi-task mode.

examples:: dp test -m graph.pb -s /path/to/system -n 30

9.3.5. compress

(Supported backend: TensorFlow) compress a model

dp compress [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
            [-m {master,collect,workers}] [-i INPUT] [-o OUTPUT] [-s STEP]
            [-e EXTRAPOLATE] [-f FREQUENCY] [-c CHECKPOINT_FOLDER]
            [-t TRAINING_SCRIPT]

9.3.5.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-m, --mpi-log

Possible choices: master, collect, workers

Set the manner of logging when running with MPI. ‘master’ logs only on main process, ‘collect’ broadcasts logs from workers to master and ‘workers’ means each process will output its own log

Default: “master”

-i, --input

The original frozen model, which will be compressed by the code

Default: “frozen_model.pb”

-o, --output

The compressed model

Default: “frozen_model_compressed.pb”

-s, --step

Model compression uses fifth-order polynomials to interpolate the embedding-net. It introduces two tables with different step size to store the parameters of the polynomials. The first table covers the range of the training data, while the second table is an extrapolation of the training data. The domain of each table is uniformly divided by a given step size. And the step(parameter) denotes the step size of the first table and the second table will use 10 * step as it’s step size to save the memory. Usually the value ranges from 0.1 to 0.001. Smaller step means higher accuracy and bigger model size

Default: 0.01

-e, --extrapolate

The domain range of the first table is automatically detected by the code: [d_low, d_up]. While the second table ranges from the first table’s upper boundary(d_up) to the extrapolate(parameter) * d_up: [d_up, extrapolate * d_up]

Default: 5

-f, --frequency

The frequency of tabulation overflow check(Whether the input environment matrix overflow the first or second table range). By default do not check the overflow

Default: -1

-c, --checkpoint-folder

path to checkpoint folder

Default: “model-compression”

-t, --training-script

The training script of the input frozen model

examples:: dp compress dp compress -i graph.pb -o compressed.pb

9.3.6. doc-train-input

print the documentation (in rst format) of input training parameters.

dp doc-train-input [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
                   [--out-type {rst,json}]

9.3.6.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

--out-type

Possible choices: rst, json

The output type

Default: “rst”

9.3.7. model-devi

calculate model deviation

dp model-devi [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
              [-m MODELS [MODELS ...]] [-s SYSTEM] [-S SET_PREFIX] [-o OUTPUT]
              [-f FREQUENCY] [--real_error] [--atomic] [--relative RELATIVE]
              [--relative_v RELATIVE_V]

9.3.7.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-m, --models

Frozen models file (prefix) to import. TensorFlow backend: suffix is .pb; PyTorch backend: suffix is .pth.

Default: [‘graph.000’, ‘graph.001’, ‘graph.002’, ‘graph.003’]

-s, --system

The system directory. Recursively detect systems in this directory.

Default: “.”

-S, --set-prefix

The set prefix

Default: “set”

-o, --output

The output file for results of model deviation

Default: “model_devi.out”

-f, --frequency

The trajectory frequency of the system

Default: 1

--real_error

Calculate the RMS real error of the model. The real data should be given in the systems.

Default: False

--atomic

Print the force model deviation of each atom.

Default: False

--relative

Calculate the relative model deviation of force. The level parameter for computing the relative model deviation of the force should be given.

--relative_v

Calculate the relative model deviation of virial. The level parameter for computing the relative model deviation of the virial should be given.

examples:: dp model-devi -m graph.000.pb graph.001.pb graph.002.pb graph.003.pb -s ./data -o model_devi.out

9.3.8. convert-from

(Supported backend: TensorFlow) convert lower model version to supported version

dp convert-from [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
                [-i INPUT_MODEL] [-o OUTPUT_MODEL]
                [{auto,0.12,1.0,1.1,1.2,1.3,2.0,pbtxt}]

9.3.8.1. Positional Arguments

FROM

Possible choices: auto, 0.12, 1.0, 1.1, 1.2, 1.3, 2.0, pbtxt

The original model compatibility

Default: “auto”

9.3.8.2. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-i, --input-model

the input model

Default: “frozen_model.pb”

-o, --output-model

the output model If OUTPUT_MODEL ends with ‘.pbtxt’, the provided model will be converted to pbtxt format, without version conversion.

Default: “convert_out.pb”

examples:: dp convert-from -i graph.pb -o graph_new.pb dp convert-from auto -i graph.pb -o graph_new.pb dp convert-from 1.0 -i graph.pb -o graph_new.pb

9.3.9. neighbor-stat

Calculate neighbor statistics

dp neighbor-stat [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
                 [-s SYSTEM] -r RCUT -t TYPE_MAP [TYPE_MAP ...] [--mixed-type]

9.3.9.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-s, --system

The system dir. Recursively detect systems in this directory

Default: “.”

-r, --rcut

cutoff radius

-t, --type-map

type map

--mixed-type, --one-type

treat all types as a single type. Used with se_atten descriptor.

Default: False

examples:: dp neighbor-stat -s data -r 6.0 -t O H

9.3.10. train-nvnmd

(Supported backend: TensorFlow) train nvnmd model

dp train-nvnmd [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
               [-i INIT_MODEL] [-r RESTART] [-s {s1,s2}]
               [--skip-neighbor-stat]
               INPUT

9.3.10.1. Positional Arguments

INPUT: the input parameter file in json format

9.3.10.2. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-i, --init-model

Initialize the model by the provided path prefix of checkpoint files.

-r, --restart

Restart the training from the provided prefix of checkpoint files.

-s, --step

Possible choices: s1, s2

steps to train model of NVNMD: s1 (train CNN), s2 (train QNN)

Default: “s1”

--skip-neighbor-stat

Skip calculating neighbor statistics. Sel checking, automatic sel, and model compression will be disabled.

Default: False

examples:: dp train-nvnmd input_cnn.json -s s1 dp train-nvnmd input_qnn.json -s s2 dp train-nvnmd input_cnn.json -s s1 –restart model.ckpt dp train-nvnmd input_cnn.json -s s2 –init-model model.ckpt

9.3.11. gui

Serve DP-GUI.

dp gui [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH] [-p PORT]
       [--bind_all]

9.3.11.1. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

-p, --port

The port to serve DP-GUI on.

Default: 6042

--bind_all

Serve on all public interfaces. This will expose your DP-GUI instance to the network on both IPv4 and IPv6 (where available).

Default: False

9.3.12. convert-backend

Convert model to another backend.

dp convert-backend [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
                   INPUT OUTPUT

9.3.12.1. Positional Arguments

INPUT: The input model file.
OUTPUT: The output model file.

9.3.12.2. Named Arguments

-v, --log-level

Possible choices: DEBUG, 3, INFO, 2, WARNING, 1, ERROR, 0

set verbosity level by string or number, 0=ERROR, 1=WARNING, 2=INFO and 3=DEBUG

Default: “INFO”

-l, --log-path

set log file to log messages to disk, if not specified, the logs will only be output to console

examples:: dp convert-backend model.pb model.pth dp convert-backend model.pb model.dp

Use –tf or –pt to choose the backend:: dp –tf train input.json dp –pt train input.json