Parameter Guide

This guide explains all the key parameters in py-electrostatic and how to choose them.

ElectrostaticCalculator Parameters

eta

Type: float (Angstroms) Default: 6.0

The Gaussian screening parameter for Ewald summation. Controls the width of the Gaussian charge distribution used to screen the Coulomb interaction.

How to choose:

Start with 0.5-1.0 Å for most materials
Smaller values need more k-points but give better accuracy
Larger values are faster but less accurate
Check convergence by varying η and monitoring energy/forces

Example:

calculator = calc.ElectrostaticCalculator()
calculator.eta = 0.5  # Good starting value

cutoff

Type: float (dimensionless) Default: 5.0

Determines the k-point cutoff for the reciprocal space sum. Include all k-points with \(|k| < \text{cutoff}/\eta\).

How to choose:

Start with 3.0-5.0
Higher values = more accurate but slower
Check convergence by increasing until energy stabilizes
For small cells, may need larger values

Example:

calculator.cutoff = 5.0  # Include k-points up to |k| < 5/η

use_nufft

Type: bool Default: True

Enable Non-Uniform FFT for O(N²) scaling instead of O(N³).

When to use:

True: Large systems (>50 atoms), faster for big supercells
False: Small systems, debugging, or when Julia is not available

Example:

calculator.init(structure, charges, dielectric,
                supercell=(2,2,2), use_nufft=True)

compute_stress

Type: bool Default: False (auto-detected based on Julia availability)

Enable stress tensor calculation. Requires Julia.

Example:

calculator.compute_stress = True  # Enable stress calculation

julia_speedup

Type: bool Default: True

Use Julia backend for accelerated calculations. Automatically disabled if Julia is not available.

supercell

Type: tuple(int, int, int) Default: (1, 1, 1)

The supercell dimensions when working with supercells. The calculator will automatically replicate the primitive cell effective charges.

Example:

calculator.init(primitive_structure, charges, dielectric,
                supercell=(2, 2, 2))  # 2x2x2 supercell

unique_atom_element

Type: str Default: None (uses first atom)

The atomic species used to identify the origin of the structure. There should be exactly one per primitive cell. Used for proper supercell handling.

Example:

calculator.init(structure, charges, dielectric,
                unique_atom_element="Ba")  # Use Ba as reference

Convergence Checking

Use the utility functions to check parameter convergence:

from pyelectrostatic.utils import study_cutoff_convergence

# Check how energy converges with cutoff
energies, cutoffs = study_cutoff_convergence(
    structure, charges, dielectric,
    eta=0.5, cutoffs=[3, 4, 5, 6, 7]
)

Recommended Starting Values

For most polar materials:

Parameter	Starting Value	Notes
eta	0.5-1.0 Å	Smaller for accuracy, larger for speed
cutoff	5.0	Increase if not converged
use_nufft	True	Use False only for small systems
compute_stress	True (if Julia available)	Needed for variable cell calculations

Common Issues

“No k-points for the sum”

The cell is too small for the given eta. Solutions:

Decrease eta (try 0.3-0.5)
Increase cutoff
Use a supercell

Energy not converged

Increase cutoff gradually until energy changes by < 1e-6 eV/atom.

Slow calculations

Enable use_nufft=True (requires Julia)
Increase eta slightly
Decrease cutoff (if accuracy allows)
Use Julia acceleration