The cyclic cluster model (CCM)¶

The cyclic cluster model is vibe-qc’s signature approach to periodic systems. This page is the conceptual and API reference; for a hands-on, step-by-step run see the tutorial.

Overview¶

CCM computes the electronic structure of a crystal, surface, or polymer by treating a finite cluster under cyclic (Born-von-Karman) boundary conditions. The historical formulation evaluates that problem in real space. A finite cyclic translation group also has an exactly equivalent full Gamma-centred reciprocal character mesh; the independent aiccm2026dev-b implementation uses that identity as its numerical representation and internal reference. The infinite-crystal result is recovered by enlarging the cluster. CCM is the original motivating feature of vibe-qc and its intended long-term flagship for periodic chemistry.

Because the cluster is the system, CCM is naturally suited to localised phenomena (point defects, surfaces, adsorbates), where a single perturbation sits inside a correctly embedded periodic background. It is the real-space counterpart to the k-point routes (GDF, BIPOLE, GPW/GAPW): the same physics approached from opposite sides, since the cluster-size limit and the k-mesh-density limit coincide.

How a cyclic cluster is built¶

Wigner-Seitz image folding¶

Each atom of the cluster carries a Wigner-Seitz (WS) cell describing its periodic surroundings. Every other atom contributes to that atom through its single nearest translational image that falls inside the WS cell. An atom lying exactly on a WS face is shared between the equidistant faces with a fractional weight (\(1/n\) for \(n\) equidistant faces). vibe-qc’s construction is a faithful port of MSINDO’s neighbour-list routine.

The construction is valid only if, for every atom, the WS weights of all the images inside its cell sum to \(N-1\): every other atom of the cluster appears exactly once, counting fractional shares. vibe-qc enforces this rule and rejects a cluster that violates it rather than returning a wrong number (CLAUDE.md § 7).

Madelung embedding¶

A finite cluster misses the conditionally-convergent long-range Coulomb tail of the infinite lattice. CCM restores it with a classical Ewald (Madelung) embedding, summed in 1, 2, or 3 dimensions according to the cluster’s periodicity. The embedding is controlled by the madelung option, which is on by default and recommended for ionic systems.

Convergence to the periodic limit¶

As the cluster grows, the WS environment of each atom converges to the bulk environment and the CCM total energy approaches the true periodic limit. The cluster-size convergence series is the CCM analogue of k-mesh convergence in a Bloch calculation; the equivalence is made explicit in the H-chain ancestor tutorial.

Running CCM¶

CCM ships today at the semi-empirical MSINDO level. There are two entry points. The high-level one goes through run_job, with the cluster atoms in a Molecule and the lattice in CCMOptions:

import vibeqc as vq
from vibeqc.semiempirical.methods.msindo_ccm import CCMOptions

res = vq.run_job(
    mol,
    method="ccm",
    ccm_options=CCMOptions(
        translations=[[a, 0, 0], [0, a, 0], [0, 0, a]],
        madelung=True,
    ),
)

The direct one is run_ccm, taking the geometry and lattice as arrays:

from vibeqc.semiempirical.methods.msindo_ccm import run_ccm

res = run_ccm(atomic_numbers, coords_angstrom, translations_angstrom,
              madelung=True)

An independent experimental ab-initio RHF/RKS route is also selectable through the periodic runner. Its kpoints tuple is the cyclic-cluster size, not an independently chosen integration mesh:

res = vq.run_periodic_job(
    system,
    basis,
    method="RHF",
    jk_method="aiccm2026dev-b",
    kpoints=(4, 4, 4),
    aiccm_backend="four_center",  # or "ri" / "rijcosx"
)
print(res.energy, res.aiccm2026dev_b.density_idempotency_error)

This development route is neutral, closed-shell, and zero-temperature. It supports 1D, 2D, and 3D RHF/RKS (including hybrids) through four-centre, RI, and RIJCOSX backends. The lower-dimensional four-center and RI long-range gauges are not yet an absolute-energy parity pair; see the B-stream page for that caveat. Its mathematical definition, boundary weights, Coulomb gauge, variational space, and disagreements with the historical weighting are documented in the independent derivation.

Keywords and defaults¶

CCMOptions (and the keyword arguments of run_ccm):

Keyword	Default	Meaning
`translations`	(required)	The 1 to 3 supercell lattice vectors, in Angstrom. The count sets the dimensionality: 1 vector is CCM1D (a polymer), 2 is CCM2D (a surface), 3 is CCM3D (bulk).
`madelung`	`True`	Add the long-range Ewald (Madelung) electrostatic embedding. Recommended for ionic systems; the dimensionality of the embedding follows the number of translation vectors.

Nuclear gradients (Ha/bohr) come in two flavours, both holding the Wigner-Seitz topology fixed: ccm_gradient_fd (central finite differences) and ccm_gradient_analytic (the analytic derivative, exact for 1-D / 2-D / 3-D including the Madelung embedding, closed-shell). Both are C++-backed. ccm_optimize relaxes the structure (selected atoms) on the CCM energy surface.

Scope and validation¶

Each limit below is a clean error, not a silent wrong answer (CLAUDE.md § 7):

Closed-shell (RHF) only. A cell with multiplicity != 1 raises.
Single point through run_job. optimize=True raises; use ccm_optimize for geometry relaxation.
Elements H to Zn, the MSINDO engine’s supported set.

CCM energies are validated out-of-process against reference MSINDO to better than 1 µHa (CLAUDE.md § 10).

The ab-initio CCM roadmap¶

The semi-empirical engine is the proving ground; the destination is ab-initio CCM, the project’s v2.x track: HF-CCM (v2.0), density fitting in CCM (v2.1), MP2-CCM (v2.2), orbital localisation and local correlation, CCSD and CCSD(T)-CCM, and projection-based embedding (v2.8) as the capstone. The full sequence is in the roadmap.

The earlier ab-initio development track carries pair-derived Wigner–Seitz weights into three- and four-centre integrals. The independent aiccm2026dev-b track does not assume those formulae: it weights only tied representatives of complete finite-translation equivalence classes, which preserves ERI permutation symmetry and a scalar RHF functional. The derivation gives both the argument and the recorded disagreement.

The four-center Coulomb and exchange weighting is itself under active comparison: two versions, union12 and aiccm2026dev-a, are kept side by side and cataloged on the experimental features page.

References¶

Bredow, Geudtner and Jug, J. Comput. Chem. 22, 89 (2001): the semi-empirical CCM that the current engine ports.
Peintinger and Bredow, J. Comput. Chem. 35, 839 (2014), doi:10.1002/jcc.23550: the cluster-choice problem and the ab-initio CCM foundation.
Peintinger, Elektronenstruktur von Molekülkristallen (dissertation, Rheinische Friedrich-Wilhelms-Universität Bonn, 2013): the primary derivation of the ab-initio CCM, published as the 2014 paper above.