Call cpmdc from Python

The Python package in python/cpmdc is a handle around one CPMDCSession. It loads libcpmdc with ctypes. Positions are Angstrom. Session returns Hartree and Hartree/Bohr, the native units of the C ABI. Potential returns eV and eV/Angstrom so an rgpot calculator can call evaluate and caps without importing cpmdc’s ASE module.

Load the library

Set CPMDC_LIBRARY to the shared library, or pass the path to Session. The search is the rgpot order: an explicit path, then CPMDC_LIBRARY, RGPOT_CPMDC_ENGINE, and RGPOT_CPMD_ENGINE. A periodic cell is encoded as ForceInput, so set CPMDC_SCHEMA to schema/Potentials.capnp or pass that path as schema.

from cpmdc import Session

with Session(open("water.params.bin", "rb").read(), library="build/libcpmdc.so") as session:
    done = session.energy_forces(
        [[0.0, 0.0, 0.1173], [0.0, 0.7572, -0.4692], [0.0, -0.7572, -0.4692]],
        [8, 1, 1],
    )
print(done.energy_h, done.forces_h_bohr)

An empty buffer, a message that is not CPMDParams, a missing library, a non-finite coordinate, or an atomic number outside 1..118 raises CpmdcError or ValueError. None of those calls abort the process. find_library and find_schema resolve the two paths. HARTREE_TO_EV and BOHR_TO_ANGSTROM are the conversion constants from the C sources. forces_to_ev_per_angstrom and stress_to_ev_per_angstrom3 apply them. Evaluation is the native result: energy_h, forces_h_bohr, and stress_h_bohr3 when a periodic cell was computed.

Use it as an rgpot provider

Potential.evaluate(positions, numbers, box) returns energy in eV, forces in eV/Angstrom, and stress as nine row-major eV/Angstrom3components when the library computed a tensor. Potential.caps returns stress=True and energies=False. An rgpot RgpotCalculator accepts any object with those two methods, so this provider can sit behind it.

from cpmdc import Potential

with Potential(open("water.params.bin", "rb").read()) as pot:
    print(pot.caps())
    print(pot.evaluate([[0.0, 0.0, 0.0], [0.0, 0.0, 0.98]], [8, 1]))

Use it as an ASE calculator

CPMDCCalculator is an ASE Calculator. Energy and free energy are eV and are the same value. Forces are eV/Angstrom. Stress, when the cell is fully periodic, is Voigt order (xx, yy, zz, yz, xz, xy) in eV/Angstrom3. A cluster omits the cell. A mixed periodic flag raises ValueError and names the open axes.

The smallest program is examples/python/ase_energy.py. The ASE tutorial runs it. examples/python/energy.py is the same step without ASE, in Hartree.

The reference harmonic well drawn by docs/render_reference_well.py is the shape of an isolated one-atom step at a 70 Ry cutoff:

Reference harmonic well, energy against displacement

Reference well for one hydrogen atom. The script writes this figure from the evaluator formula.

The curve is zero at the origin and rises on both sides.

One session, one composition

The first successful step fixes the atom count and the elemental composition. A later step with a different composition needs a new Session. The handle is not shared across threads.