Analysis Features

Analysis

FBTK’s analysis features accept ASE objects or trajectory data directly and process them using a high-speed Rust engine.

Direct Analysis of ASE Objects

Functions like fbtk.compute_rdf and fbtk.compute_msd can take ASE Atoms objects or a list of them directly as arguments.

RDF Example: Analyzing a Copper Crystal

import fbtk
from ase.build import bulk

# Create a Copper FCC crystal (4x4x4 supercell, 256 atoms)
atoms = bulk('Cu', 'fcc', a=3.614) * (4, 4, 4)

# Compute RDF (r_max=10.0 A, 100 bins)
r, g_r = fbtk.compute_rdf(atoms, query="element Cu", r_max=10.0, n_bins=100)

# Display peak positions
print("RDF Result (Cu FCC):")
for i in range(20, 50):
    print(f"  r = {r[i]:.2f} A, g(r) = {g_r[i]:.2f}")

Output Example:

RDF Result (Cu FCC):
  r = 2.05 A, g(r) = 0.00
  r = 2.15 A, g(r) = 0.00
  ...
  r = 2.55 A, g(r) = 17.33  <-- 1st neighbor peak
  r = 2.65 A, g(r) = 0.00
  ...
  r = 3.65 A, g(r) = 4.23   <-- 2nd neighbor peak
  ...
  r = 4.45 A, g(r) = 7.28   <-- 3rd neighbor peak

MSD Example: Trajectory Analysis

FBTK provides high-speed Mean Squared Displacement (MSD) calculation, essential for estimating diffusion coefficients.

import fbtk
from ase.io import read

# Load a trajectory file (e.g., 100 frames)
traj = read("traj.lammpstrj", index=":")

# Compute MSD
# dt: Time interval between frames (e.g., saved every 1000 steps, dt=1000)
res = fbtk.compute_msd(traj, query="resname SOL", dt=1000.0)

# Display results
print("MSD Result:")
for i in range(4):
    print(f"  t = {res['time'][i]:.1f}, MSD = {res['msd'][i]:.3f}")

Output Example:

MSD Result:
  t = 0.0, MSD = 0.000
  t = 1000.0, MSD = 0.005
  t = 2000.0, MSD = 0.018
  t = 3000.0, MSD = 0.033

---

Smart Query Semantics

FBTK uses a powerful query language to select atom groups. It distinguishes between group filtering (and) and pair definition (with or -).

1. Group Filtering (and)

Combines multiple conditions to define a single group of atoms.

• resname SOL and element O: Selects atoms that belong to residue “SOL” AND are the element “O”.

2. Pair Definition (with or -)

Used in RDF analysis to separate the two groups whose correlation you want to calculate.

• GroupA with GroupB or GroupA - GroupB: Defines the correlation between Group A (source) and Group B (target).

# Example: Correlation between Water (WAT) Oxygen (O) and Solute (ION)
fbtk.compute_rdf(atoms, query="resname WAT and element O with resname ION")

---

Practical Query Examples

1. Elements and Residue Names

• element C: All Carbon atoms.
• resname POLY: All atoms belonging to the residue named “POLY”.

2. Explicit Atom Indices (ID)

Select specific atoms pinpointed by their zero-indexed ID or a range.

• index 0 1 2 5 10: Select a specific list of atom IDs.
• index 0 to 99: Select atoms with IDs from 0 to 99.
• index 0 to 49 with index 50 to 99: Compute correlation between two specific ID ranges.

---

ASE-Compatible Analysis Methods

Standard analysis tasks frequently performed on ASE Atoms objects are accelerated by the Rust backend.

# Analysis on a System object (or Atoms via fbtk.from_ase)
distances = system.get_all_distances(mic=True)  # Shortest distance considering PBC
com = system.get_center_of_mass()                # Center of Mass
neighbors = system.get_neighbor_list(cutoff=5.0) # Neighbor List generation