BELLO (Bond Element Lattice Locality Order) is a post-processing toolkit for characterizing local structural order in amorphous and disordered materials. It works with standard XYZ trajectory files produced by any atomistic simulation code (DFT, MD, etc.) and provides automated identification of coordination environments, order-parameter statistics, radial/angular distribution analysis, and publication-ready visualizations — all through a cross-platform graphical interface with Chinese/English language support.

Keywords: amorphous materials, disordered solids, coordination analysis, Steinhardt order parameter, radial distribution function (RDF), VASP POSCAR/XDATCAR converter, materials science GUI, computational materials science.

• Local-order classification — automatically identifies 0- through 6-fold coordination, tetrahedral, and octahedral motifs for every atom in every frame
• Order parameter q — computes the Steinhardt-type bond-orientational order parameter to quantify structural regularity
• Automatic threshold — determines the nearest-neighbor cutoff from the first peak of the radial distribution function via Gaussian fitting
• Radial pair distribution function — calculates partial g(r) for any element pair across multi-frame trajectories
• Angle distribution function — sorts bond angles by element triplet and plots histograms with kernel-density-estimation fits
• Coordination heatmap — generates Seaborn heatmaps showing the frequency of element combinations in each coordination type
• VASP → XYZ converter — reads POSCAR / CONTCAR / XDATCAR files and converts them to XYZ, auto-detecting file type and auto-filling cell dimensions; XDATCAR multi-frame trajectories are fully supported
• Embedded plots — all figures render inside the GUI with full Matplotlib navigation (zoom, pan, save)
• Chinese / English UI — one-click language toggle in the top-right corner
• Large-trajectory acceleration controls — Frame stride and Max frames let you sample long trajectories for faster turnaround
• Safe run lock — repeated clicks on Calculate while a task is running are ignored to prevent concurrent-run conflicts

• Python 3.9 or later
• tkinter (included with standard Python installers; see platform notes below)

macOS / Linux

git clone https://github.com/OldJii/BELLO.git
cd BELLO
chmod +x setup.sh
./setup.sh

Windows

git clone https://github.com/OldJii/BELLO.git
cd BELLO
setup.bat

The setup script creates a virtual environment, installs all dependencies, and checks for tkinter availability.

# macOS / Linux
source .venv/bin/activate
python BELLO_GUI.py

# Windows
.venv\Scripts\activate.bat
python BELLO_GUI.py

1. Click Browse and select an XYZ trajectory file.
2. Enter the unit-cell dimensions (X, Y, Z in Angstroms).
3. Set the inter-atomic distance Threshold and Tolerance, or check Automatic threshold to let the program determine them from the RDF first peak.
4. (Optional for speed) Set Frame stride and Max frames in the Parameters card:
   • Frame stride = 1 means use every frame
   • Frame stride = 10 means use every 10th frame
   • Max frames = 0 means no limit
5. Select BELLO Analysis and click Calculate.
6. When finished, the right panel shows:
   • Plot 1 — Order-parameter q distribution (smoothed, per fold type)
   • Plot 2 — Local-order population vs. frame number
7. Output files are written to the working directory (output-*.txt, out2.pdb, etc.).

1. Load an XYZ file and fill in cell dimensions as above.
2. Select RDF — a dialog asks for maximum radius, step size, and the two element symbols.
3. (Optional for speed) Reuse Frame stride and Max frames settings from the Parameters card.
4. Click Calculate. The partial g(r) curve appears in the plot panel; data is saved to RDF.txt.

Requires a prior BELLO run (needs output-angle-distribution.txt).

1. Select Angle Distribution — enter the element symbols present in your system.
2. Click Calculate. Per-triplet histograms with KDE fits appear as separate tabs. Sorted data is saved under Sorted_angles/.

Requires a prior BELLO run (needs output-human-readable-coords.txt).

1. Select Coordination Heatmap — enter element symbols.
2. Click Calculate. Heatmaps show the frequency of each element combination in 3-fold through octahedral environments.

1. In the VASP → XYZ Converter card, click Browse and select a VASP file (.vasp, POSCAR, CONTCAR, or XDATCAR).
2. Click Convert. The file type is auto-detected:
   • POSCAR / CONTCAR — single-frame conversion
   • XDATCAR — all frames are extracted into one multi-frame XYZ trajectory, ready for BELLO analysis
3. The converted .xyz file path is auto-filled into the input field, and cell dimensions are populated from the lattice vectors.

Click the 中文 / English button in the top-right corner. The entire interface rebuilds in the selected language instantly.

BELLO/
├── BELLO_GUI.py                          # GUI (tkinter, cross-platform)
├── BELLO_main.py                         # Core analysis engine
├── Radial_Pair_Distribution_Function.py  # Partial RDF calculation
├── Angle_Distribution_Function.py        # Angle sorting and plotting
├── Coordination_Heatmap.py               # Coordination heatmap generation
├── vasp_converter.py                     # VASP POSCAR/CONTCAR/XDATCAR → XYZ
├── xyz_reader.py                         # Robust XYZ file parser
├── test.xyz                              # Sample trajectory (270 Ge atoms)
├── requirements.txt                      # Python dependencies
├── setup.sh                              # macOS / Linux setup script
├── setup.bat                             # Windows setup script
└── .gitignore

All installed automatically by the setup script:

• numpy
• pandas
• scipy
• matplotlib
• seaborn

What is BELLO used for?
Analyzing local structural order in amorphous or disordered atomistic systems — coordination environments, bond-orientational order parameter q, RDF, angle distributions, and coordination heatmaps from MD/DFT trajectories.

What input files does BELLO accept?
Standard multi-frame XYZ trajectories. VASP files (POSCAR, CONTCAR, XDATCAR) can be converted to XYZ via the built-in converter.

Does BELLO require a specific simulation code?
No. Any code that exports XYZ (or VASP structure files) is compatible.

What is the order parameter q?
A Steinhardt-type bond-orientational order parameter that quantifies how regular the local bonding geometry is around each atom.

Is BELLO free and open source?
Yes. Clone from GitHub and run locally with Python 3.9+.

Which languages does the GUI support?
English and Chinese — toggle instantly from the top-right corner.

Where can AI assistants read a structured summary?
See llms.txt in this repository (LLMO / AI SEO friendly).