Command Line Interface (CLI)

Command Line Interface

FBTK provides fast, statically-linked binary tools that can be operated directly from the shell without installing Python.

Installation (Standalone Binary)

In addition to the Python library, executables for major platforms (Linux / macOS / Windows) are distributed on the GitHub Releases page.

# Example: Download and place the Linux binary (v0.9.8)
wget https://github.com/ForblazeProject/fbtk/releases/download/v0.9.8/fbtk-cli-v0.9.8-linux-x86_64.tar.gz
tar -xzf fbtk-cli-v0.9.8-linux-x86_64.tar.gz
cd fbtk-cli-v0.9.8-linux-x86_64
chmod +x fbtk-build fbtk-analyze
mv fbtk-build fbtk-analyze ~/bin/  # Move to a directory in your PATH

Available Commands

FBTK runs with 4 threads by default for parallel execution.

fbtk-build: System Construction from Recipe

Packs molecular systems and exports the structure based on a YAML recipe file. Note: The --recipe (or -r) flag is required.

# Basic usage
fbtk-build --recipe recipe.yaml --output system.mol2

# Perform structural relaxation after construction
fbtk-build --recipe recipe.yaml --relax --output relaxed.mol2

# Run with a specific number of threads
fbtk-build --recipe recipe.yaml --threads 8 --output system.mol2

fbtk-analyze: Fast Analysis Pipeline

Reads LAMMPS or GROMACS trajectory files and performs analysis on specified atom groups.

Automatic Format Detection

Files with the .gro extension are automatically loaded as GROMACS format. All other extensions are treated as LAMMPS dump files.

Computing Radial Distribution Function (RDF)

# Analyze LAMMPS dump file (using Type query)
fbtk-analyze rdf traj.dump --query "type 1 with type 2" --output rdf.dat

# Analyze GROMACS gro file (using Element query)
# * Elements (O, H, Cl, etc.) are automatically guessed from .gro atom names
fbtk-analyze rdf trajectory.gro --query "element O with element H" --output rdf_gro.dat

Computing Mean Squared Displacement (MSD)

# Analyze diffusion of specific element groups (dt=1000 fs)
fbtk-analyze msd trajectory.gro --query "element C" --dt 1000.0 --output msd.dat

Enhanced High-Precision Output and SMILES Support

The latest CLI tools feature engine core improvements for better reliability:

Multi-frame GROMACS Support: Native support for multi-frame .gro files containing multiple simulation steps.
Advanced MOL2 Files: Coordinate and charge output precision has been increased to 6 decimal places. Component names from recipes are used as residue names, and unique residue IDs are automatically assigned to each molecule.
Accurate Ion Construction: Improvements to the SMILES parser ensure correct hydrogen counts and valency for charged species like [NH4+] or [O-].
Ecosystem Compatibility: Generated MOL2 files maintain high quality for direct use in downstream pipelines such as OpenFF, GROMACS, and LAMMPS.

Controlling Parallelism via Environment Variables

Similar to the Python version, you can control the number of threads using the RAYON_NUM_THREADS environment variable.

export RAYON_NUM_THREADS=16
fbtk-build --recipe recipe.yaml --output system.mol2