Skip to main content

RIPER: ASE Calculator for TURBOMOLE

riper is an ASE calculator interface for the RIPER module in TURBOMOLE: Kohn-Sham DFT with Gaussian basis sets for molecules and for systems with one-, two- or three-dimensional periodicity. The calculator writes the TURBOMOLE coord and control files, runs riper, and returns energies, forces, the stress tensor, dipole and magnetic moments, orbital energies, occupations and k points in ASE units. Band structures, densities of states, RT-TDDFT spectra and cube files are one method call each.

Version 0.3 keeps the RIPERCalculator interface of 0.2.x (scripts written for 0.2.x run unchanged) on a new backend built on ASE's template-calculator API. It targets TURBOMOLE 8.1 and exposes only features documented in the 8.1 manual.

Installation

From PyPI:

pip install riper

For development from this repository:

pip install -e .
pytest tests                                         # unit tests on recorded outputs
RIPER_TEST_COMMAND=riper_smp pytest tests/test_integration.py   # needs riper

Requirements: TURBOMOLE 8.1 or newer, Python >= 3.9, ASE >= 3.23, NumPy.

TURBOMOLE environment

Before using the calculator, make sure TURBOMOLE is configured in the shell where Python runs, for example:

export TURBODIR=/path/to/TURBOMOLE
export TURBOIMG=/path/to/TURBOMOLE
export PARA_ARCH=SMP
source $TURBODIR/Config_turbo_env
command -v riper_smp

The calculator does not ship TURBOMOLE. It calls the executable selected with riper_command (riper, riper_smp or a full path); ncore sets the thread-count variables (PARNODES, OMP_NUM_THREADS, MKL_NUM_THREADS) for the RIPER subprocess only. Without riper_command the [riper] section of ~/.config/ase/config.ini is used if present (command = riper_smp, ncore = 8), otherwise riper from PATH.

Before the first calculation the calculator runs riper once on a one-atom input (0.3 s, cached per command) and reads the version from the banner. Versions older than 8.1 are rejected with a clear error, a missing executable is reported before any input is written, and the detected version is available as calc.riper_version (check_version=False skips the probe).

Quick start: water single point

from ase.build import molecule
from riper import RIPERCalculator

water = molecule("H2O")
water.calc = RIPERCalculator(
    functional="pbe",
    basis="def2-SVP",
    auxbasis="universal",
    dipole=True,
    riper_command="riper_smp",
    directory="calculations/water_pbe",
)

energy = water.get_potential_energy()      # eV
forces = water.get_forces()                # eV/Angstrom
dipole = water.get_dipole_moment()         # e*Angstrom
band_gap = water.calc.get_band_gap()       # eV
print(water.calc.get_eigenvalues().round(2), water.calc.get_fermi_level())

After a successful run band_gap, efermi (Fermi level) and dipole_moment are also stored in atoms.info, so an extXYZ export (ase.io.write("water.extxyz", water)) carries them together with energy, forces, stress and magnetic moments.

Periodic example: silicon with stress and band structure

from ase.build import bulk
from riper import RIPERCalculator

si = bulk("Si", "diamond", a=5.43)
si.calc = RIPERCalculator(
    functional="pbe",
    basis="pob-TZVP-rev2",
    auxbasis="universal",
    nkpoints=[4, 4, 4],
    calculate_stress=True,
    riper_command="riper_smp",
    directory="calculations/si",
)

print(si.get_potential_energy(), si.get_stress())   # eV, eV/Angstrom^3 (ASE Voigt order)
bs = si.calc.band_structure("GXWKGL", npoints=100)  # ase.spectrum.band_structure.BandStructure
bs.subtract_reference().plot(filename="si_bands.png", emin=-12, emax=8)
dos = si.calc.get_dos(width=0.1, pdos={"elements": ["si"], "resolve": "l"})

The periodicity follows atoms.pbc: zero, one, two or three periodic directions. RIPER needs chains along x and slabs in the xy plane; the calculator rotates any orientation (nanotubes along z, slabs with pbc=[True, False, True], tilted in-plane vectors) into RIPER's frame and rotates forces, stress and dipoles back. No vacuum is needed in non-periodic directions. For 2D systems only the entries of nkpoints belonging to the periodic cell vectors are used, for 1D one entry.

Calculator parameters

RIPERCalculator(
    basis=None, auxbasis="universal", ecp=None,
    functional="pbe", nkpoints=None,
    charge=0, uks=False, unpaired=0,
    smear=False, sigma=0.01, desnue=None,
    dispersion=None,
    scfconv=7, scfiterlimit=50, denconv=None, ricore=5000, gridsize="m5",
    riper_command=None, ncore=None, directory=".",
    extra_keywords=None, extra_groups=None,
    convergence_check="error",
    calculate_stress=False, dipole=False, plot_dens=False, forces=None, restart=True,
    dftu=None, relativistic=None, kramers=False,
    check_version=True,
)
Option Type / units Meaning
basis str, dict or None Orbital basis. If None, def2-SVP for 0D and pob-DZVP-rev2 for periodic systems. A dict assigns per element, e.g. {"Mg": "pob-DZVP-rev2", "O": "pob-TZVP-rev2"}.
auxbasis str or dict Auxiliary basis, default universal, written as jbas.
ecp str, dict or None Effective core potential, e.g. "def2-ecp"; a dict assigns per element.
functional str TURBOMOLE functional keyword (pbe, b3-lyp, pbe0, hse06, scan0, ...). xc is accepted as a synonym.
nkpoints list of int or dict k-point mesh; only the periodic directions are written. Default [2, 2, 2]. {"density": 4.0} chooses the mesh from a k-point density (per 1/Angstrom). kpts is accepted as a synonym. Even subdivisions are written as nkpoints n n n shifted (the 8.1 mesh; newer versions honour the word and then give the same numbers).
charge int Total charge ($atomdens total_charge).
uks bool Unrestricted Kohn-Sham ($uhf).
unpaired int Unpaired electrons ($atomdens unpaired), implies uks=True.
smear, sigma bool, Hartree Gaussian smearing with width sigma ($riper sigma).
desnue float Fixed number of unpaired electrons per cell in smeared UKS runs ($riper desnue).
dispersion None, "d3", "d3bj", "d4" $disp3, $disp3 bj or $disp4. disp3=True is accepted for "d3".
scfconv, scfiterlimit, denconv, ricore, gridsize TURBOMOLE meaning $scfconv N (10^-N Hartree), $scfiterlimit, $denconv, $ricore (MB), grid size.
riper_command, ncore str, int Executable and thread count for the RIPER subprocess (see above).
extra_keywords dict Additional $riper sub-keywords, e.g. {"epssmt": "1.0d-8", "marij": False}.
extra_groups dict Additional data groups, e.g. {"$title": ["my run"], "$marij": []}.
convergence_check "error", "warning", "ignore" What to do when the SCF does not converge (RIPERConvergenceError, a warning, or nothing). calc.converged records the outcome.
calculate_stress bool Compute the stress tensor in every periodic run (also computed on demand). stress=True is accepted as a synonym.
dipole bool Compute the dipole moment in every run ($fields electric on; also on demand).
plot_dens bool Write the density cube td.cub in every run ($pointvalper fmt=cub).
forces bool or None Compute the gradient (default yes, except with dftu).
restart bool Reuse RIPER.BANDS of the directory when basis, functional, mesh, charge, spin and smearing are unchanged (stale files are removed otherwise).
dftu dict Dudarev DFT+U, {"zn": ("d", 10.0)} with U_eff in eV ($dftpu); energies only in 8.1.
relativistic, kramers "2c", bool Two-component calculation ($soghf, use dhf-*-2c basis sets and dhf-ecp-2c), Kramers-restricted with kramers=True.
directory str Working directory.

Unknown keywords raise a TypeError.

Results

calc.results uses ASE's names: energy (RIPER TOTAL ENERGY; with smearing the energy extrapolated to zero smearing, ENERGY (sigma->0)), free_energy (FREE ENERGY, the quantity forces and stress are consistent with; atoms.get_potential_energy(force_consistent=True)), forces (from the gradient file), stress (ASE Voigt order, sigma = (1/V) dE/deps with the ASE cell volume; negative diagonal = the cell wants to expand), dipole, magmom (unpaired electrons from P*S), fermi_level, eigenvalues (nspins, nkpts, nbands), occupations, ibz_kpoints, kpoint_weights, nbands, nspins, nkpts (from riper_bands.txt), band_gap, vbm, cbm (RIPER's Fermi level statistics), riper_energies (all printed energy terms in eV), scf_cycles, riper_version.

With these, calc.get_eigenvalues(), calc.get_fermi_level(), ase.dft.dos.DOS(calc) and ase.dft.bandgap.bandgap(calc) work. For shifted even meshes RIPER lists the Gamma point in addition to the mesh (weight 0); 8.1 includes it in the band-gap statistics.

Post-SCF tasks

Each task reruns riper in the calculation directory, restarting from the converged bands, with its output in riper.<task>.out.

Method riper input Returns
band_structure(path=None, npoints=60, density=None, projected=None) $kpoints kptlines along the ASE band path ase.spectrum.band_structure.BandStructure (eV, reference = Fermi level); with projected={"elements": [...], "atoms": [...], "resolve": "l"} the Mulliken fat-band weights as bs.projections
get_dos(width=0.1, npts=1000, emin=None, emax=None, pdos=None) $dosper (+ $pdosper) DOSResult: energies (eV), fermi_level, total, columns (s, p, ...), projections (el_o, at1_mg, ... -> columns), files
rttddft_spectrum(resolution=None, polarization="iso") `$rttddft spectrum [fine] [iso x
write_cubes(["dens"]) $pointvalper fmt=cub list of cube files

width, emin, emax are in eV (converted to Hartree for riper); the DOS window defaults to Fermi level -20 eV ... +15 eV.

Files written

coord, control, riper.out, gradient, .riper_ase.json (bookkeeping: frame rotation, restart fingerprint) and, from riper, riper_bands.txt, the restart files RIPER.BANDS*, mos/alpha/beta, and per task riper.bands.out/bands.xyz/ bands_proj.xyz, riper.dos.out/dos/pdos_*, riper.rttddft.out/rtspec, riper.cubes.out/*.cub.

Changes from 0.2.9

Scripts written for 0.2.9 run unchanged. Behaviour that changed: energies of smeared runs follow the ASE convention above; forces come from the gradient file ($grad file=gradient is written) instead of the $grad block in control; stress is read from the current RIPER output (the formats 0.2.x parsed no longer exist); even meshes are written with shifted; structures in any orientation are handled; stale RIPER.BANDS files are removed when the electronic settings change; the riper version is checked once. See CHANGELOG.md.

Examples

examples/example01 to example23 cover single points, optimisations, 1D/2D/3D systems, stress and cell optimisation, NEB, vibrations, phonons, hybrid functionals, dispersion, cube files, dipoles, smearing/desnue, ECPs and mixed basis sets. example24 to example36 show the additions of 0.3: results overview, band structure, DOS/PDOS, equation of state, molecular dynamics, bilayer graphene stacking, CO on a MgO slab, open-shell/charged molecules, DFT+U, RT-TDDFT spectrum, 1c versus 2c iodine, hybrid band gap versus k mesh, elastic constants from the stress tensor. Each script writes into calculations/.

Contact

Manas Sharma

Metadata

Release files for riper 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for riper 0.3.0
File Size Uploaded Provenance Actions
riper-0.3.0.tar.gz 105.9 kB Without provenance Details for riper-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for riper 0.3.0
File Interpreter ABI Platform Actions
riper-0.3.0-py3-none-any.whl Python 3 none any Details for riper-0.3.0-py3-none-any.whl

Total release size: 142.5 kB

Release files / riper-0.3.0.tar.gz

Download URL riper-0.3.0.tar.gz
Size 105.9 kB
Tags Source
SHA-256 checksum
How to use checksums
4d436f9f950edc5682302f9e20181e74e44974d0609c24e20033c4b51f617040
BLAKE2b-256 checksum
How to use checksums
7f8cf018523eee33989c4ec49261a9501b30fa568a6dee8f8ed83014fd0efb86
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Release files / riper-0.3.0-py3-none-any.whl

Download URL riper-0.3.0-py3-none-any.whl
Size 36.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4732db8f104e0923ecb35e961d8ae292d9847217b966a0eabb58578a946d5f10
BLAKE2b-256 checksum
How to use checksums
7fe9ca9c4fadf8e480a91a60ffd1758e4be2d57ed133b4044b1d8277ea9b758b
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}

Security for riper 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page