====================== 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``. .. code:: python 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/Angstrom\ :sup:`3`\ components 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. .. code:: python 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/Angstrom\ :sup:`3`\. 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 :doc:`ASE tutorial <../tutorials/ase-energy>` 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: .. figure:: /_static/reference-well.svg :alt: 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.