# Command guide
<style>
  p {
    text-align: justify;
  }
</style>
Various tasks can be performed through the command line interface of PFD-kit. Here is a guide to the available commands.

## Making perturbed structures
The initial structures for exploration can be generated by perturbing availiable frames. For example, ten perturbed structures for the diamond Si system can be prepared by the following command: 
```bash
pfd perturb -n 10 dia_si.extxyz -c 0.03
``` 
The input file can be of any ase-compatible format. The perturbed frames are stored in `pert_dia_si.extxyz`.

## Submitting a Workflow

To submit a workflow, navigate to the working directory and run:

```bash
pfd submit input.json
```

`input.json` contains workflow definitions. The workflow ID will be printed upon successful submission.

## Checking status
To check the status of exploration, use:

```bash
pfd status input.json workflow_id
```

## Restarting from a Checkpoint

To restart a workflow with modified input parameters, use:

```bash
pfd resubmit input.json old_workflow_id -u 0-100
```

This reuses the results of the first 100 steps of an old workflow. To list completed steps:

```bash
pfd resubmit input.json old_workflow_id -l
```

## Downloading Results

To download the output model file, use:

```bash
pfd download input.json workflow_id
```

For advanced usage, download a specific step's output:

```bash
pfd download input.json workflow_id -i 0 -d prep-run-train/input/models
```

List available download definitions:

```bash
pfd download input.json workflow_id -l
```

## PFD-kit Command Arguments

> Note: Use `-h` or `--help` to list all possible arguments for PFD-kit subcommands.

### Subcommand: `perturb`
Usage:
```bash
pfd perturb [-h] [-n PERT_NUM] [-c CELL_PERT_FRACTION] [-d ATOM_PERT_DISTANCE] [-s ATOM_PERT_STYLE] [-a ATOM_PERT_PROB] [-r SUPERCELL [SUPERCELL ...]] ATOMS [ATOMS ...]
```
Arguments:

- `ATOMS`: the structure files in ase-compatible format, support multiple files.
- `-n PERT_NUM, --pert-num PERT_NUM`: the number of perturbed structures to be generated for each input structure. (default: 1) 
- `-c CELL_PERT_FRACTION, --cell-pert-fraction CELL_PERT_FRACTION`: the fraction of cell perturbation. (default: 0.05)
- `-d ATOM_PERT_DISTANCE, --atom-pert-distance ATOM_PERT_DISTANCE`: the distance to perturb the atom. (default: 0.2)
- `-s ATOM_PERT_STYLE, --atom-pert-style ATOM_PERT_STYLE`: the style of perturbation. (default: normal)
- `-a ATOM_PERT_PROB, --atom-pert-prob ATOM_PERT_PROB`: the probability of perturbing each atom. (default: 1.0)
- `-r SUPERCELL [SUPERCELL ...], --supercell SUPERCELL [SUPERCELL ...]`: the supercell replication, support int or 3 ints. (default: None)


### Subcommand: `submit`
Usage:
```bash
pfd submit [-h] [-m] CONFIG
```
Arguments:

- `CONFIG`: Path to the configuration script in `json` format.
- `-m, --monitoring`: Monitor workflow progress and auto-download the output model upon successful completion.

### Subcommand: `status`
Usage:
```bash
pfd status [-h] CONFIG ID
```
Arguments:

- `CONFIG`: Path to the configuration script in `json` format.
- `ID`: Workflow ID of an existing PFD workflow.

### Subcommand: `resubmit`
Usage:
```bash
pfd resubmit [-h] [-m] CONFIG ID
```
Arguments:

- `CONFIG`: Path to the configuration script in `json` format.
- `ID`: Workflow ID of an existing PFD workflow.
- `-l, --list`: List completed steps of an existing workflow.
- `-u, --reuse REUSE`: Reuse completed steps from an existing workflow.
- `-f, --fold`: Reuse dflow `Steps` in the workflow as a whole. For instance, failed LAMMPS tasks would be skipped in the resubmitted workflow if the `prep-run-explore` `Steps` it belongs to is asserted as successful.   
- `-m, --monitoring`: Monitor workflow progress and auto-download the output model upon successful completion.

### Subcommand: `download`
Usage:
```bash
pfd download [-h] [-l] [-k KEYS] [-i ITERATIONS] [-d STEP_DEFINITIONS] [-p PREFIX] [-n] CONFIG ID
```
Arguments:

- `CONFIG`: Path to the configuration script in `json` format.
- `ID`: Workflow ID of an existing PFD workflow.
- `-k, --keys KEYS`: Download artifacts by step key(s).
- `-d, --step-definitions STEP_DEFINITIONS`: Download artifacts by *step definitions*.
- `-l, --list-supported`: List all supported step definitions.
- `-i, --iterations ITERATIONS`: Specify steps from which iterations are to be downloaded. Used in conjuntion with `-d STEP_DEFINITIONS`.
- `-p, --prefix PREFIX`: Prefix for the download path.