Command line interface

9. Command line interface#

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

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

9.1. Named Arguments#

-b, --backend

Possible choices: jax, tensorflow, tf, pytorch, pt

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

Default: “tensorflow”

--jax

Alias for –backend jax

--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, change-bias, train-nvnmd, gui, convert-backend, show

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]
         [--use-pretrain-script] [-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.

--use-pretrain-script

When performing fine-tuning or init-model, utilize the model parameters provided by the script of the pretrained model rather than relying on user input. It is important to note that in TensorFlow, this behavior is the default and cannot be modified for fine-tuning.

Default: False

-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]
          [--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

--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] [--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 the datafile, each line of which is a path to one data system.

-S, --set-prefix

[DEPRECATED] Deprecated argument.

-n, --numb-test

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

Default: 0

-r, --rand-seed

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

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

Default: False

--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#

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. Filename (prefix) of the input model file. TensorFlow backend: suffix is .pb; PyTorch backend: suffix is .pth

Default: “frozen_model”

-o, --output

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

Default: “frozen_model_compressed”

-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 –tf compress -i frozen_model.pb -o compressed_model.pb dp –pt compress -i frozen_model.pth -o compressed_model.pth

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,json_schema}] [--multi-task]

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, json_schema

The output type

Default: “rst”

--multi-task

Print the documentation of multi-task training input parameters.

Default: False

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

[DEPRECATED] Deprecated argument.

-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. If not provided, the type map of data will be used.

--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. change-bias#

(Supported backend: PyTorch) Change model out bias according to the input data.

dp change-bias [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
               [-s SYSTEM | -f DATAFILE | -b BIAS_VALUE [BIAS_VALUE ...]]
               [-n NUMB_BATCH] [-m {change,set}] [-o OUTPUT]
               [--model-branch MODEL_BRANCH]
               INPUT

9.3.10.1. Positional Arguments#

INPUT: The input checkpoint file or frozen model file

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

-s, --system

The system dir. Recursively detect systems in this directory

Default: “.”

-f, --datafile

The path to the datafile, each line of which is a path to one data system.

-b, --bias-value

The user defined value for each type in the type_map of the model, split with spaces. For example, ‘-93.57 -187.1’ for energy bias of two elements. Only supports energy bias changing.

-n, --numb-batch

The number of frames for bias changing in one data system. 0 means all data.

Default: 0

-m, --mode

Possible choices: change, set

The mode for changing energy bias: change (default) : perform predictions using input model on target dataset, and do least square on the errors to obtain the target shift as bias. set : directly use the statistic bias in the target dataset.

Default: “change”

-o, --output

The model after changing bias.

--model-branch

Model branch chosen for changing bias if multi-task model.

examples:: dp change-bias model.pt -s data -n 10 -m change

9.3.11. 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.11.1. Positional Arguments#

INPUT: the input parameter file in json format

9.3.11.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.12. 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.12.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.13. 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.13.1. Positional Arguments#

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

9.3.13.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

9.3.14. show#

Show the information of a model

dp show [-h] [-v {DEBUG,3,INFO,2,WARNING,1,ERROR,0}] [-l LOG_PATH]
        INPUT {model-branch,type-map,descriptor,fitting-net}
        [{model-branch,type-map,descriptor,fitting-net} ...]

9.3.14.1. Positional Arguments#

INPUT: The input checkpoint file or frozen model file
ATTRIBUTES: Possible choices: model-branch, type-map, descriptor, fitting-net

9.3.14.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 –pt show model.pt model-branch type-map descriptor fitting-net dp –pt show frozen_model.pth type-map descriptor fitting-net

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

Command line interface

Contents

9. Command line interface#

9.1. Named Arguments#

9.2. Valid subcommands#

9.3. Sub-commands#

9.3.1. transfer#

9.3.1.1. Named Arguments#

9.3.2. train#

9.3.2.1. Positional Arguments#

9.3.2.2. Named Arguments#

9.3.3. freeze#

9.3.3.1. Named Arguments#

9.3.4. test#

9.3.4.1. Named Arguments#

9.3.5. compress#

9.3.5.1. Named Arguments#

9.3.6. doc-train-input#

9.3.6.1. Named Arguments#

9.3.7. model-devi#

9.3.7.1. Named Arguments#

9.3.8. convert-from#

9.3.8.1. Positional Arguments#

9.3.8.2. Named Arguments#

9.3.9. neighbor-stat#

9.3.9.1. Named Arguments#

9.3.10. change-bias#

9.3.10.1. Positional Arguments#

9.3.10.2. Named Arguments#

9.3.11. train-nvnmd#

9.3.11.1. Positional Arguments#

9.3.11.2. Named Arguments#

9.3.12. gui#

9.3.12.1. Named Arguments#

9.3.13. convert-backend#

9.3.13.1. Positional Arguments#

9.3.13.2. Named Arguments#

9.3.14. show#

9.3.14.1. Positional Arguments#

9.3.14.2. Named Arguments#