# FBTK: Forblaze Toolkit

![PyPI - Version](https://img.shields.io/pypi/v/fbtk)
[![Documentation](https://img.shields.io/badge/docs-latest-blue)](https://fbtk.forblaze-works.com/)

High-performance molecular analysis and building tools powered by Rust.
Designed as a "Transparent Accelerator" for Python (ASE/RDKit) workflows with a smart, object-oriented interface.

## Features

- **🚀 High Performance**: Core logic written in Rust with parallel processing (Rayon).
- **🏗️ Intelligent Builder**: 
  - **Optimized Initial Packing**: Grid-based placement with uniform density.
  - **Polymer Synthesis**: Automatic chain generation with leaving atom support.
  - **Tacticity Control**: Supports **Isotactic**, **Syndiotactic**, and **Atactic** arrangements via center-of-mass analysis and mirroring.
  - **Built-in 3D Generation**: 3D coordinate generation from SMILES handled by internal VSEPR + UFF engine.
  - **Fast Structural Relaxation**: O(N) Cell-list optimization with the FIRE algorithm.
- **🔍 Advanced Analysis**: 
  - Parallel RDF, MSD, COM (Center of Mass), Angles, Dihedrals.
  - O(N) Neighbor List search.
- **📏 Robust Physics**: Correct handling of PBC, Triclinic cells, and Minimum Image Convention (MIC).

## Installation

### Python Library (Recommended)
```bash
pip install fbtk
```
**Requirements**: Python 3.8+ and NumPy.

### Standalone CLI (No Python Required)
For non-Python environments, pre-compiled standalone binaries for Linux, Windows, and macOS are available on the [GitHub Releases](https://github.com/ForblazeProject/fbtk/releases) page.
- Download the archive for your platform (e.g., `fbtk-cli-v0.9.1-linux-x86_64.tar.gz`).
- **Requirements**: None. These are self-contained binaries.

## Usage

### 1. System Building

Build and relax a complex molecular system with just a few lines of code.

```python
import fbtk

# 1. Setup Builder
builder = fbtk.Builder(density=0.8)
builder.add_molecule_smiles("ethanol", count=50, smiles="CCO")

# 2. Build and Relax
system = builder.build()
system.relax(steps=500)

# 3. Export to ASE
atoms = system.to_ase()
atoms.write("system.xyz")
```

### 2. RDF Analysis

Fast analysis of large trajectories using smart selection queries.

```python
from ase.io import read
import fbtk

# Load trajectory (ASE list of Atoms)
traj = read('simulation.lammpstrj', index=':')

# Compute RDF using a simple query string
r, g_r = fbtk.compute_rdf(traj, query="O-H", r_max=10.0)
```

---

### 3. Command Line Interface (CLI)

FBTK provides standalone CLI tools for batch processing.

#### fbtk-build: Build from Recipe
```bash
# Run building and relaxation from a YAML recipe
fbtk-build --recipe recipe.yaml --relax --output system.mol2
```

Example `recipe.yaml`:
```yaml
system:
  density: 0.8
  cell_shape: [20.0, 20.0, 20.0]
components:
  - name: "ethanol"
    role: "molecule"
    input:
      smiles: "CCO"
    count: 50
```

#### fbtk-analyze: Analyze Trajectory
```bash
# Compute RDF for a LAMMPS trajectory
fbtk-analyze rdf --input traj.lammpstrj --query "type 1 with type 2"
```

## Selection Query Syntax

FBTK supports intuitive strings to select atoms for analysis:

- **Element**: `"O"`, `"H"`, `"element C"`
- **Pairs (RDF)**: `"O-H"`, `"C - C"`
- **Index Range**: `"index 0:100"` (start:end)
- **Residue**: `"resname STY"`

---
### Author
**Forblaze Project**  
Website: [https://forblaze-works.com/en/](https://forblaze-works.com/en/)

