tricor

Generate disordered atomic supercells guided by three-body (g3) distributions, spanning the full spectrum from liquid to nanocrystalline. Designed for machine-learning training data generation.

Documentation

Installation

pip install tricor

# Optional data-IO extras
pip install 'tricor[data]'        # h5py, zarr

Or to install the development checkout:

git clone https://github.com/ophusgroup/tricor
cd tricor
uv sync                # or: pip install -e '.[test]'

tricor requires Python ≥ 3.10 and works on Linux, macOS, and Windows.

Quick start - Si

from ase.build import bulk
import tricor as tc

atoms = bulk('Si', 'diamond', a=5.431)
shell_target = tc.CoordinationShellTarget.from_atoms(
    atoms,
    phi_num_bins=90,
)

cell = tc.Supercell.from_atoms(
    atoms,
    cell_dim_angstroms=(40, 40, 40),
    r_max=10,
    r_step=0.1,
    phi_num_bins=90,
    relative_density=0.96,
    rng_seed=42,
)
cell.generate(
    shell_target,
    num_steps=150,
    grain_size=13.0,
    bond_weight=1.9,
    angle_weight=0.9,
    repulsion_weight=2.5,
    hard_core_scale=0.95,
    nonbond_push_scale=0.7,
    displacement_sigma=0.04,
)

cell.measure_g3()
cell.plot_g3()

cell.plot_structure(output='structure.mp4')

Quick start - SiC (binary)

atoms = bulk('SiC', 'zincblende', a=4.36)
shell_target = tc.CoordinationShellTarget.from_atoms(
    atoms,
    phi_num_bins=90,
)

cell = tc.Supercell.from_atoms(
    atoms,
    cell_dim_angstroms=(40, 40, 40),
    r_max=10,
    r_step=0.1,
    phi_num_bins=90,
    relative_density=0.96,
    rng_seed=42,
)
cell.generate(
    shell_target,
    num_steps=150,
    grain_size=13.0,
    bond_weight=1.9,
    angle_weight=0.9,
    repulsion_weight=2.5,
    hard_core_scale=0.95,
    nonbond_push_scale=0.7,
    displacement_sigma=0.04,
)

cell.measure_g3()
cell.plot_g3()  # browse Si | Si Si, C | C C, etc.

Structure generation

generate() builds disordered structures by combining Voronoi grain construction with spring-network relaxation.

Recommended presets for Si

Available as Supercell.PRESETS:

cell = tc.Supercell.from_atoms(
    atoms,
    (40, 40, 40),
    rng_seed=42,
)
cell.generate(shell_target, **tc.Supercell.PRESETS["MRO"])

All presets use relative_density=0.96. Abbreviations: rep_wt = repulsion_weight, hc_scale = hard_core_scale, nbp_scale = nonbond_push_scale.

Optional: target g3 for comparison

To compare the supercell against a target distribution, create one explicitly and pass it as the initial distribution:

dist = tc.G3Distribution(atoms)
dist.measure_g3(
    r_max=10,
    r_step=0.1,
    phi_num_bins=90,
)
target = dist.target_g3(
    target_r_min=5.0,
    target_r_max=8.0,
    r_sigma=0.05,
    phi_sigma_deg=3.0,
)

cell = tc.Supercell(
    target,
    cell_dim_angstroms=(40, 40, 40),
    relative_density=0.96,
)
cell.generate(
    shell_target,
    grain_size=13.0,
    bond_weight=1.9,
    angle_weight=0.9,
    repulsion_weight=2.5,
    hard_core_scale=0.95,
    nonbond_push_scale=0.7,
    displacement_sigma=0.04,
)
cell.measure_g3()
cell.plot_g3_compare()

Core classes

• G3Distribution - measures rooted three-body angle/distance histograms from atomic structures
• CoordinationShellTarget - extracts first-shell coordination targets (bond lengths, angles, coordination numbers) from a reference crystal
• Supercell - generates and optimises disordered supercells

Dependencies

• numpy, matplotlib, ase, anywidget
• Optional: h5py, zarr (for data I/O)