(api_reference_cli_tool_link)=

# API reference for the command-line tool (jqmc-tool)

`jqmc-tool` provides ancillary CLI utilities for TREXIO conversion, Hamiltonian inspection/conversion, and pre/post-processing of VMC/MCMC/LRDMC workflows. Typical invocation:

```bash
jqmc-tool <group> <command> [options]
# or, module-style
python -m jqmc.jqmc_tool <group> <command> [options]
```

Groups: `trexio`, `hamiltonian`, `vmc`, `mcmc`, `lrdmc`.

---

## `trexio` group

### `show-info`
Show concise metadata stored in a TREXIO file.

```
jqmc-tool trexio show-info <filename>
```
- `filename` (arg): TREXIO file.

### `show-detail`
Dump full objects (structure, AOs, MOs, geminal, Coulomb).

```
jqmc-tool trexio show-detail <filename>
```
- `filename` (arg): TREXIO file.

### `convert-to`
Convert TREXIO to `hamiltonian_data.h5` with optional Jastrow setup.

```
jqmc-tool trexio convert-to <trexio_file> [options]
```
- `-o, --output` (str, default `hamiltonian_data.h5`): Output filename.
- `-j1, --jastrow-1b-parameter` (float|None): J1 parameter. If set and ECP is present, core electrons are taken from ECP; otherwise zeroed.
- `--jastrow-1b-type` (`exp|pade`, default `exp`): Functional form of the one-body Jastrow. `exp` uses $u(r) = \frac{1}{2b}(1 - e^{-br})$; `pade` uses $u(r) = \frac{r}{2(1 + br)}$.
- `-j2, --jastrow-2b-parameter` (float|None): J2 parameter.
- `--jastrow-2b-type` (`pade|exp`, default `pade`): Functional form of the two-body Jastrow. `pade` uses $v(r) = \frac{r}{2(1+br)}$; `exp` uses $v(r) = \frac{1}{2b}(1-e^{-br})$.
- `-j3, --jastrow-3b-basis-set-type` (`ao|ao-full|ao-small|ao-medium|ao-large|mo|none`, default `none`): Choose J3 basis; `ao-*` trims AOs by key exponent grouping, `mo` uses MOs, `none` disables J3.
- `-j-nn-type, --jastrow-nn-type` (str|None): Add NN Jastrow (e.g., `schnet`).
- `-jp, --jastrow-nn-param` (repeatable `key=value`): Hyperparameters forwarded to `Jastrow_NN_data.init_from_structure`; supported keys (type, default): `hidden_dim (int, 64)`, `num_layers (int, 3)`, `num_rbf (int, 16)`, `cutoff (float, 5.0)`.
- `--ao-conv-to` (`cart|sphe|None`, default `None`): Convert AOs after building the Hamiltonian. `cart` converts all AO representations (Geminal and Jastrow three-body) to Cartesian GTOs; `sphe` converts them to real spherical-harmonic GTOs. When omitted (`None`), the original representation from the TREXIO file is kept.

Outputs an HDF5 `Hamiltonian_data` with Jastrow/Geminal embedded.

---

## `hamiltonian` group

### `show-info`
Print metadata from an existing Hamiltonian HDF5/checkpoint.

```
jqmc-tool hamiltonian show-info <hamiltonian_data>
```

### `to-xyz`
Export nuclear geometry to XYZ (Bohr -> Å).

```
jqmc-tool hamiltonian to-xyz <hamiltonian_data> [-o struct.xyz]
```

### `conv-wf`
Convert wavefunction ansatz inside a Hamiltonian file.

```
jqmc-tool hamiltonian conv-wf <hamiltonian_data> -c {jsd|jagp} [-o output.h5]
```
- `-c, --convert-to`: `jagp` converts SD→AGP (AOs); `jsd` is not implemented.

---

## `vmc` group (pre/post utilities)

### `generate-input`
Emit a VMC `toml` template (sets `control.job_type = "vmc"`).

```
jqmc-tool vmc generate-input -g [-f vmc.toml] [--without-comment]
```

### `analyze-output`
Parse VMC optimization logs (energies, |f|, signal-to-noise) and optionally plot.

```
jqmc-tool vmc analyze-output <log...> [-p] [--save-graph file]
```

---

## `mcmc` group (pre/post utilities)

### `compute-energy`
Jackknife estimator of VMC energy from an MCMC restart archive.

```
jqmc-tool mcmc compute-energy <restart_chk> [-b N] [-w W]
```
- `-b, --num_mcmc_bin_blocks` (int, default 1): Binning blocks per MPI × walker; total blocks = `b * mpi_size * walkers`. Must be ≥ `MCMC_MIN_BIN_BLOCKS`.
- `-w, --num_mcmc_warmup_steps` (int, default 0): Discarded warmup measurements; must be ≥ `MCMC_MIN_WARMUP_STEPS`.

### `compute-force`
Jackknife estimator of VMC atomic forces (Hellmann–Feynman + Pulay) from an MCMC restart archive.  Requires that the MCMC run was performed with `atomic_force = true`.

```
jqmc-tool mcmc compute-force <restart_chk> [-b N] [-w W]
```
- `-b, --num_mcmc_bin_blocks` (int, default 1): Binning blocks per MPI × walker; total blocks = `b * mpi_size * walkers`. Must be ≥ `MCMC_MIN_BIN_BLOCKS`.
- `-w, --num_mcmc_warmup_steps` (int, default 0): Discarded warmup measurements; must be ≥ `MCMC_MIN_WARMUP_STEPS`.

Outputs a per-atom force table in Ha/bohr with jackknife error bars.

### `generate-input`
Emit an MCMC `toml` template (sets `control.job_type = "mcmc"`).

```
jqmc-tool mcmc generate-input -g [-f mcmc.toml] [--without-comment]
```

---

## `lrdmc` group (pre/post utilities)

### `compute-energy`
Jackknife estimator of LRDMC energy from an LRDMC restart archive.

```
jqmc-tool lrdmc compute-energy <restart_chk> [-b N] [-w W] [-c C]
```
- `-b, --num_gfmc_bin_blocks` (int, default 5): Binning blocks per MPI × walker (note: total blocks = `b`, not multiplied by ranks × walkers). Must be ≥ `GFMC_MIN_BIN_BLOCKS`.
- `-w, --num_gfmc_warmup_steps` (int, default 0): Discarded warmup steps; must be ≥ `GFMC_MIN_WARMUP_STEPS`.
- `-c, --num_gfmc_collect_steps` (int, default 5): Pre-binning measurements used to collect weights; must be ≥ `GFMC_MIN_COLLECT_STEPS`.

### `compute-force`
Jackknife estimator of LRDMC atomic forces (Hellmann–Feynman + Pulay) from an LRDMC restart archive.  Requires that the LRDMC run was performed with `atomic_force = true`.

```
jqmc-tool lrdmc compute-force <restart_chk> [-b N] [-w W] [-c C]
```
- `-b, --num_gfmc_bin_blocks` (int, default 5): Binning blocks per MPI × walker. Must be ≥ `GFMC_MIN_BIN_BLOCKS`.
- `-w, --num_gfmc_warmup_steps` (int, default 0): Discarded warmup steps; must be ≥ `GFMC_MIN_WARMUP_STEPS`.
- `-c, --num_gfmc_collect_steps` (int, default 5): Pre-binning measurements used to collect weights; must be ≥ `GFMC_MIN_COLLECT_STEPS`.

Outputs a per-atom force table in Ha/bohr with jackknife error bars.

### `extrapolate-energy`
Fit energy vs $a^2$ from multiple LRDMC restart archives and extrapolate $a\to 0$.

```
jqmc-tool lrdmc extrapolate-energy <restart_chk...> [-p order] [-b N] [-w W] [-c C] [-g] [--save-graph file]
```
- `-p, --polynomial-order` (int, default 2): Fit $E(a^2) = E_0 + a^2 E_2 + a^4 E_4 + \dots$.
- Other options as in `compute-energy`.

### `generate-input`
Emit an LRDMC `toml` template (sets `control.job_type = "lrdmc-bra"`).

```
jqmc-tool lrdmc generate-input -g [-f lrdmc.toml] [--without-comment]
```

---

## Notes on variational parameters (when NN Jastrow is enabled)
- All trainable weights/biases of the NN Jastrow (message, receiver, readout networks) plus spin and species embeddings are treated as variational parameters within VMC.
- NN hyperparameters are provided via `-j-nn-type` and `-jp key=value` on `trexio convert-to`; unsupported keys are passed through and validated by `Jastrow_NN_data.init_from_structure`.
