Materials Assembly

sci-form supports assembly of Metal-Organic Frameworks (MOFs) and other crystalline structures from Secondary Building Units (SBUs) and topological blueprints. This module handles periodic unit cells, coordination geometries, and framework construction.

Unit Cell and Lattice Vectors

Lattice Parameters

A crystallographic unit cell is defined by six parameters:

Parameter	Symbol	Description
$a,b,c$	Lengths	Edge lengths in Ångströms
$\alpha$	Angle	Angle between $\overrightarrow{b}$ and $\overrightarrow{c}$
$\beta$	Angle	Angle between $\overrightarrow{a}$ and $\overrightarrow{c}$
$\gamma$	Angle	Angle between $\overrightarrow{a}$ and $\overrightarrow{b}$

Lattice Matrix

The lattice vectors are stored as rows of a $3\times 3$ matrix $M$:

$$M=\left(\begin{array}{c}\overrightarrow{a}\\ \overrightarrow{b}\\ \overrightarrow{c}\end{array}\right)$$

For the general triclinic case:

$$\overrightarrow{a}=(a,0,0)$$$$\overrightarrow{b}=(b\cos \gamma ,b\sin \gamma ,0)$$$$\overrightarrow{c}=(c\cos \beta ,c\frac{\cos \alpha -\cos \beta \cos \gamma }{\sin \gamma },c\cdot v)$$

where $v$ ensures the correct volume.

Coordinate Transforms

Fractional → Cartesian:

$${\overrightarrow{r}}_{\text{cart}}=M^T\cdot \overrightarrow{f}$$

Cartesian → Fractional:

$$\overrightarrow{f}=(M^{-1}{)}^T\cdot {\overrightarrow{r}}_{\text{cart}}$$

Volume

$$V=\overrightarrow{a}\cdot (\overrightarrow{b}\times \overrightarrow{c})=det(M)$$

Periodic Boundary Conditions

Wrapping fractional coordinates into $[0,1)$:

$${\overrightarrow{f}}_{\text{wrapped}}=\overrightarrow{f}-\lfloor \overrightarrow{f}\rfloor$$

Minimum image distance under periodicity:

$$\mathrm{\Delta }\overrightarrow{f}=\mathrm{\Delta }\overrightarrow{f}-\text{round}(\mathrm{\Delta }\overrightarrow{f})$$$$d=|M^T\cdot \mathrm{\Delta }\overrightarrow{f}|$$

Supercell Generation

A $(n_a\times n_b\times n_c)$ supercell replicates atoms at:

$${\overrightarrow{f}}_{ijk}=\frac{{\overrightarrow{f}}_0+(i,j,k)}{(n_a,n_b,n_c)},i\in [0,n_a),j\in [0,n_b),k\in [0,n_c)$$

Lattice vectors scale: ${\overrightarrow{a}}^{\prime }=n_a\overrightarrow{a}$, etc.

Framework Assembly

Assembly Pipeline

1. Select topology: Define node positions and edge connectivity (pcu, dia, sql, etc.)
2. Place metal nodes: Position SBU at each topology vertex with appropriate coordination geometry
3. Orient linkers: Use Rodrigues rotation to align linker SBUs along each edge direction
4. Build crystal: Combine all atoms with fractional coordinates into a CrystalStructure

Topologies

Topology	Coordination	Nodes	Edges	Description
pcu	6	1	3	Primitive cubic — octahedral nodes
dia	4	2	4	Diamond — tetrahedral nodes
sql	4	1	2	Square lattice — square planar nodes

SBU Types

Metal Node: A central metal atom with connection points arranged in the specified coordination geometry.

let node = Sbu::metal_node("Zn", 2.0, CoordinationGeometry::Tetrahedral);

Linear Linker: A bridging unit connecting two metal nodes.

let linker = Sbu::linear_linker(&["C", "C", "C"], 1.4, "BDC");

Rodrigues Rotation

Linkers are oriented from the default $\hat{x}$ direction to the edge direction using the Rodrigues rotation formula:

$$R(\overrightarrow{v})=\overrightarrow{v}\cos \theta +(\hat{k}\times \overrightarrow{v})\sin \theta +\hat{k}(\hat{k}\cdot \overrightarrow{v})(1-\cos \theta )$$

where $\hat{k}$ is the rotation axis (normalized cross product of $\hat{x}$ and the target direction) and $\theta$ is the angle between them.

API

Rust

use sci_form::{create_unit_cell, assemble_framework};

let cell = create_unit_cell(10.0, 10.0, 10.0, 90.0, 90.0, 90.0);
let crystal = assemble_framework("Zn", "BDC", "pcu", &cell);

CLI

# Unit cell info
sci-form cell --a 10 --b 10 --c 10 --alpha 90 --beta 90 --gamma 90

# Framework assembly
sci-form assemble --topology pcu --a 10.0 --metal Zn --geometry octahedral

Python

import sci_form
cell = sci_form.unit_cell(10.0, 10.0, 10.0, 90.0, 90.0, 90.0)
print(cell.volume())       # 1000.0
print(cell.parameters())   # (a, b, c, alpha, beta, gamma)

crystal = sci_form.assemble_framework("pcu", 10.0, "Zn", "octahedral")
print(crystal.num_atoms())

Validation

• Cubic cell: Volume $=a^3$, all angles 90°
• Coordinate roundtrip: frac → cart → frac recovers original
• PBC wrapping: All fractional coords in $[0,1)$ after wrapping
• Minimum image: Distance is always ≤ half the cell diagonal
• Supercell scaling: $(2\times 2\times 2)$ supercell has 8× the atoms