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. For any one already specified block-circulant finite Hamiltonian, its real-supercell and full Gamma-centred character-mesh representations are exactly Fourier equivalent. The independent χ-CCM implementation (jk_method="aiccm2026dev-b") uses that internal identity. It does not identify the χ construction with the union-and-weight Γ-CCM construction. 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, zero-temperature, and currently 3D-only. Four-centre, RI, and RIJCOSX backends support 3D RHF/RKS, including hybrids where the selected backend implements their exchange. Every 1D/2D backend fails closed until a shared neutral wire/slab Green function and matching electrostatic terms are derived; see the χ-CCM 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 Xe, 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 χ-CCM 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. The aiccm2026dev-a Γ-CCM line uses the union-and-weight/Wigner–Seitz integral-weighting construction; the aiccm2026dev-b χ-CCM line uses the finite-translation-group character construction. They are distinct approaches compared at a declared common exchange-q=0 convention. The convention does not assign them different Coulomb kernels, and equality for any specified operator and route remains evidence to establish.

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.