Vaspin

A Python package for handling VASP input files, currently only supports handling POSCAR files.

Development Setup

uv sync --all-extras
pre-commit install

Basic usage

Currently we only support handling POSCAR files, so things we can do is limited. But more will come.

Read POSCAR file

just import the Poscar class and pass the path to the POSCAR file to it.

from vaspin import Poscar
path_to_poscar = "PATH/TO/POSCAR"
pos = Poscar.from_file(path_to_poscar)

Build from data

You can also build the Poscar manually, using the PosData dataclass, The input follows the same format as elemental entries in POSCAR.

from vaspin import Poscar
from vaspin import PosData

posdata = PosData(
    lattice=input_lattice,
    species=input_species,
    number=input_number,
    frac=input_frac # now we just support build from fractional coordinates
)

we use a simple POSCAR file to show the relevant attributes of the PosData dataclass.

Cubic BN        # PosData.comment
3.57            # PosData.coe
0.0 0.5 0.5     # PosData.lattice
0.5 0.0 0.5     # PosData.lattice
0.5 0.5 0.0     # PosData.lattice
B N             # PosData.species
1 1             # PosData.number
Direct
0.00 0.00 0.00  # PosData.frac
0.25 0.25 0.25  # PosData.frac

Get coordinates

POSCAR generally has two coordinates type, cartesian and fractional, and they are stored in the coor_cate and coor_frac attributes.

cate = pos.coor_cate
frac = pos.coor_frac

As default, only one type of coordinates is stored in the POSCAR file, and Poscar will automatically convert the coordinates to the other using the lattice attribute. You can also convert the coordinates manually using the cate2frac and frac2cate methods. The lattice required for conversion defaults to the lattice attribute, but you can also pass a different lattice to the methods.

frac_from_cate = pos.cate2frac(cate)
cate_from_frac = pos.frac2cate(frac)

frac_trans_otherlattice = pos.cate2frac(cate, lattice=other_lattice)
cate_from_otherlattice = pos.frac2cate(frac, lattice=other_lattice)

Generate random displacement

# unit random displacement along x, y, z direction with 0.2 Angstrom magnitude
displacement = pos.random_disp(magnitude=0.2, method='cate')

# unit random displacement along a sphere inside the sphere with 0.2 Angstrom magnitude
displacement = pos.random_disp(magnitude=0.2, method='sphere')

# get distorted catesian coordinates
displaced_coor = pos.coor_cate + displacement

Write POSCAR file

# write to POSCAR file using default settings
pos.write_poscar()

# the lattice, atoms list, and coordinates, when not given, will be taken from the Poscar object
pos.write_poscar(
    lattice: FloatArray | None = None,
    atoms: StrArray | None = None,
    coor_frac: FloatArray | None = None,
    directory: str = ".",
    comment: str = "generated by mother python",
    name: str = "POSCAR",
)

create point defects

You can generate Vacancy and substitution defects in the Poscar.

posdata_vac = pos.defect_create_vac(coor_frac=input_coor_frac)
posdata_sub = pos.defect_create_sub(coor_frac=input_coor_frac, atom=input_atom)

# create new Poscar from the PosData and write to new POSCAR
pos_vac = Poscar(posdata_vac)
pos_sub = Poscar(posdata_sub)
pos_vac.write_poscar()
pos_sub.write_poscar()