Metadata-Version: 2.4
Name: py-electrostatic
Version: 0.2
Summary: Force-field to calculate long-range electrostatic interactions in polar materials
Author-email: Lorenzo Monacelli <lorenzo.monacelli@alumni.iu.edu>
License: GPL-3.0
Project-URL: Homepage, https://github.com/mesonepigreco/py-electrostatic
Project-URL: Repository, https://github.com/mesonepigreco/py-electrostatic
Project-URL: Issues, https://github.com/mesonepigreco/py-electrostatic/issues
Keywords: physics,electrostatics,polar-materials,forcefield,condensed-matter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: scipy
Requires-Dist: ase
Requires-Dist: cellconstructor
Requires-Dist: julia
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# Electrostatic Calculator
A python calculator that can calculate the electrostatic long-range forces and stress tensor from Born effective charges and the dielectric tensor.

## Citation

If you use this code in your research, please cite:

**L. Monacelli and N. Marzari**, *Electrostatic interactions in atomistic and machine-learned potentials for polar materials*, **Phys. Rev. B 113, 094101 (2026)**.  
[https://doi.org/10.1103/7ygl-8db2](https://doi.org/10.1103/7ygl-8db2)

## Documentation

Full documentation is available at: **https://mesonepigreco.github.io/py-electrostatic/**

The documentation includes:
- Installation guide
- Tutorials (getting started, supercells, composite calculator, SSCHA integration)
- API reference
- Theory guide

## Requirements

1. CellConstructor
2. ASE
3. julia

The requirements can be installed as

```
pip install -r requirements.txt
```

But **julia must be installed on the machine**. 
Julia is not a necessary dependency (the calculator will work anyway) but it may be very slow for computing energies of big systems.


If you are not using anaconda and need root privileges, add the --user flag at the end of the command.

## Installation

The code can be installed like any python package with

```
python setup.py install
```

also in this case, add the --user option if you need root privileges.

The 


## Usage

The pyelectrostatic can be used as a simple ASE calculator.

If julia is installed, you can exploit julia acceleration by running with **python-jl** instead of python command. 

It requires to run to have effective charges and the dielectric tensor of a reference structure.

It is interfaced with CellConstructor, 
and these information can be read from the standard Quantum-Espresso dynamical matrix.

Here an example

```
    # Load CellConstructor to import the quantum-espresso dynamical matrix
    import cellconstructor as CC, cellconstructor.Phonons    
    import pyelectrostatic, pyelectrostatic.calculator as calc
    import numpy as np

    # The example dynamical matrix is located in tests/BaTiO3/BaTiO3_1
    # It contains the dielectric tensor, centroid structure and effective charges
    dyn = CC.Phonons.Phonons("BaTiO3_")

    # Now setup the calculator and initialize the dielectric tensor and effective charges
    calculator = calc.ElectrostaticCalculator()
    calculator.init_from_phonons(dyn)

    # Get a reference structure (randomize the atomic position to have a non zero dipole moment)
    struct = dyn.structure.copy()
    struct.coords[:,:] += np.random.normal(size = struct.coords.shape, scale = 0.05)

    # Get the ASE Atoms 
    ase_atoms = struct.get_ase_atoms()

    # Setup the calculator
    ase_atoms.set_calculator(calculator)

    # Now use it as a normal calculator:
    print("Energy = ", ase_atoms.get_total_energy(), " eV")
    print("Total forces [eV/A] is:")
    print(ase_atos.get_forces())
```


We employed cellconstructor Phonon class to read a quantum espresso dinamical matrix.
You can setup the calculation even without one, by directly passing the centrinds, effective charges, dielectric tensor and the supercell size:

```
    calculator.init(centroids = structure, effective_charges = eff_charges, dielectric_tensor = diel_tensor, supercell = (2,2,2))
```

Where structure is a CellConstructor Structure, eff_charges is a numpy array of size (n_atoms, 3, 3)
(atomic index, electric field polarization, cartesian coordinate of the atom)
and diel_tensor is a symmetric 3x3 numpy array.

A working example is shown in Examples/compute_energy_forces/compute_energy_forces.py

Run it with
```
python-jl compute_energy_forces.py
```

Remember to install julia on the system. The first run needs to compile the julia code, therefore the timing for the first energy/force calculation may take few seconds.

For more info, look at the tests inside the tests directory and see the calculator at work!


