ZStar

ZStar is an automated toolkit for polarization, Born effective charges, dielectric response, and infrared and Raman spectra calculations. Its principal workflow uses ABACUS, PYATB, and Phonopy.

Highlights

• Unified symmetry-adapted BEC/APT, Gamma force constants and static nonresonant Raman derivatives from the same calculations. Retained electronic matrices supply additional PYATB responses without additional SCFs.
• Molecular atomic polar tensors (APT) from ABACUS + PYATB or CP2K dipoles.
• Symmetry reduction, full-cell reconstruction, and acoustic-sum-rule correction.
• Serial and resumable 0.no-move -> displacements execution.
• Reuse of the converged reference charge density.
• A one-time insulating-state gate using a normal band path by default.
• Shell, Slurm, and Torque/PBS drivers with Specified, Current, or Global headers.
• Legacy and direct-static-response PYATB compatibility.
• Hybrid 1D BECs: transverse charge-density dipoles plus longitudinal Berry polarization.
• Hybrid 2D BECs: Berry-phase in-plane response plus cube-integrated out-of-plane dipole.
• IR, Raman, and static/frequency-dependent dielectric response.
• A packaged run-zstar-workflows Agent Skill with JSON preflight.
• Slab electrostatic-potential maps, directional profiles, and local two-sided vacuum diagnostics.

Examples

The four-dimensional examples compare calculated spectra with literature frequencies or published curves. Relative Raman intensities for Sb2S3 remain different from the reference; the examples document this limitation explicitly. Full inputs, results, and bilingual tutorials are in the versioned GitHub example library.

Representative archived results include Z*(Ti) = 7.440 e for cubic BaTiO3, Z*(B,parallel) = 2.702 e for monolayer hBN, (Zrr,Ztt,Zzz)_B = (0.397,1.256,2.745) e for BN(9,0), and q_GAPT(O) = -0.481 e for H2O. Periodic values are BEC components; the molecular value is the APT invariant Tr(A)/3.

Installation

Version 0.3.2 includes the Unified BEC, phonon, IR, and Raman framework. Install the version associated with the manuscript:

pip install zstar==0.3.2
zstar --version

To upgrade to the latest stable release:

pip install -U zstar
zstar --version

Python 3.9 or newer is required. Phonopy is installed as a Python dependency; ABACUS and PYATB must be available for workflows that use them. The core installation uses spglib for symmetry and does not require pymatgen.

For VASP vasprun.xml, CHGCAR/POTCAR, or legacy smodes/Wyckoff adapters, install the optional extra:

pip install -U "zstar[vasp]"

Configure external executables in .zstar/config.toml and verify them:

zstar config init
zstar config set executables.abacus /opt/abacus/bin/abacus
zstar config set execution.mpi 1
zstar config set execution.omp 20
zstar config check
zstar backend list --check

For ABACUS cases whose pseudopotentials and numerical orbitals are stored in shared libraries, provide their directories during preparation:

zstar bec pre --stru STRU \
  --pp /path/to/PSEUDO \
  --orb /path/to/ORBITAL

Frequently used directories can be configured globally with abacus.pseudo_dir and abacus.orbital_dir. ZStar preserves the source STRU, writes a resolved copy to .zstar/STRU.resolved, records selected files and checksums in .zstar/assets.json, and stops with an actionable error when matching files are missing or ambiguous.

Agent Skill

Install the bundled Agent Skill and open a new agent session:

zstar skill install
zstar skill preflight --root . --lane bec --dim bulk

Invoke it explicitly as $run-zstar-workflows. The skill preserves ZStar's dimensional conventions, resumable state, permission boundaries, and artifact-based completion checks. Use zstar skill install --force after upgrading the package.

Serial BEC Workflow

# Generate 0.no-move and displacement folders
zstar bec pre --stru STRU

# Run one resumable serial chain
zstar bec run

# Inspect progress
zstar bec stat --root .

# Construct symmetry-consistent BEC tensors
zstar bec post --root .

For a z-periodic 1D wire, use --dim 1 throughout. ZStar obtains the two transverse polarization columns from high-precision charge-density cubes and the longitudinal column from PYATB Berry polarization:

zstar bec pre --stru STRU --dim 1
zstar bec run --root .
zstar bec post --root .

The source snapshot includes complete BN(9,0) nanotube and Sb2S3-chain examples with clean run/ inputs, results/ archives and resumable run.sh scripts. Their BECs and Gamma force constants come from the same symmetry-adapted SCFs. Additional normal-mode polarizability derivatives provide Raman spectra. The Sb2S3 comparison retains original public reference curves and the observed Raman-intensity differences; its reference is a computational dataset, not a verified associated journal article. See the one-dimensional guide.

For an isolated molecule, --dim 0 generates and collects atomic polar tensors in units of e. The name is deliberate: an APT is the molecular analogue of a periodic-crystal BEC.

zstar bec pre --stru STRU --dim 0
zstar bec run --root .
zstar bec post --root .

For a 2D slab, use --dim 2 in generation, execution, and post-processing. Full x/y/z displacements are required because the out-of-plane polarization column is obtained from the real-space slab dipole. The slab normal must currently align with Cartesian z.

Run a complete two-dimensional response calculation through the canonical BEC lifecycle:

zstar bec pre --stru STRU --dim 2
zstar bec run
zstar bec post

The low-level zstar polar2d command is retained only for auditing an existing reference/displaced cube pair.

The default insulating gate runs only for 0.no-move and uses:

pyatb_input --band

The path gate is a lightweight fail-fast check and cannot exclude an off-path metallic pocket. Use --gap-mode mp when a stricter MP-grid check is desired.

Generate one environment-specific driver:

zstar bec job --system shell
zstar bec job --system slurm --queue compute --tasks 28
zstar bec job --system torque --queue batch --tasks 28

Shell/Torque default to mpirun -np N; Slurm defaults to srun --ntasks=N. Use --dry-run for an environment and state-output smoke test without launching an electronic-structure calculation.

Phonon, IR, and Dielectric Response

# INPUT must contain: cal_force 1
zstar phonon pre --stru STRU --dim "2 2 2"
zstar phonon run --root .
zstar phonon stat --root .
zstar phonon post --root .
zstar phonon irrep --root . --file irreps.yaml --mode db

# Copy BORN and Z-BORN-symm.out from the BEC workflow.
zstar dielectric static --qpoints qpoints.yaml --born Z-BORN-symm.out --dielectric BORN
zstar dielectric freq --qpoints qpoints.yaml --born Z-BORN-symm.out --dielectric BORN
zstar spectra pre --calculator abacus --kind ir --root ir_spectrum \
  --qpoints qpoints.yaml --born Z-BORN-symm.out --dielectric BORN
zstar spectra post --root ir_spectrum

zstar dielectric freq writes the zero-frequency tensor, real and imaginary response tables, and PNG/PDF/SVG plots by default. Use --no-plot for data-only post-processing.

For --dim 1, dielectric/IR response is reported as an Angstrom^2 line polarizability; for --dim 2, it is a sheet polarizability unless an effective --thickness is supplied. Gamma-point 1D IR/Raman is supported, while finite-q polar phonons still require a genuine 1D Coulomb cutoff and must not use bulk NAC.

Raman Workflow

The ABACUS + PYATB Unified route now uses the same displacement SCFs for BEC/APT, Gamma phonons, IR and static nonresonant Raman. In a prepared BEC directory, use zstar spectra pre, zstar spectra run, and zstar spectra post. Raman adds dielectric postprocessing of retained matrices, not additional SCFs. --response PATH selects another completed ensemble; --method mode keeps explicit normal-mode finite differences for comparison. Other calculators retain their documented native response workflows.

zstar spectra pre --calculator abacus --kind raman --root raman \
  --stru STRU --qpoints qpoints.yaml \
  --modes "4-12" --copy INPUT-scf --copy KPT

zstar spectra run --root raman --reference 0.no-move
zstar spectra post --root raman

The Raman runner reuses the reference insulating gate and charge density, records every plus/minus stage, collects central-difference dielectric derivatives, and writes a Placzek spectrum.

Isolated molecules (--dim 0)

The same mode-pair workflow can calculate normalized molecular IR and Raman spectra in one resumable run:

zstar spectra pre --calculator abacus --kind all --root raman --dim 0 \
  --stru STRU --qpoints qpoints.yaml --modes "4-12" \
  --copy INPUT-scf --copy KPT
zstar spectra run --root raman --reference 0.no-move \
  --spectrum-outdir raman_spectrum --ir-outdir ir_spectrum
zstar spectra post --root raman

ZStar converts Berry polarization through dmu/dQ = V*dP/dQ and the dilute-supercell dielectric response through dalpha/dQ = V/(4*pi)*d(epsilon_r)/dQ. Existing prepared mode-pair results can be checked with zstar spectra stat and reprocessed with zstar spectra post.

Electrostatic Potential Diagnostics

zstar pot --cube OUT.ABACUS/ElecStaticPot.cube \
  --axes z --plane xy --plane-average \
  --direction a+b --mirror-test \
  --vacuum-sides --vacuum-exclude 6.0 --vacuum-window 0.75 \
  --polar-arrow auto --outdir potential

For a dipole-corrected polar slab, the two vacuum levels are averaged in local windows next to the surface exclusion boundaries. This avoids contaminating a surface plateau with the potential-reset segment. Directional profiles such as --direction a+b and --direction a-b are inspection diagnostics rather than polarization magnitudes.

Main Outputs

Logo on PyPI

This description intentionally contains no repository-relative logo. PyPI cannot render an image stored only in a private GitHub repository. A logo must use a stable, publicly accessible HTTPS URL; relative images remain suitable for the private GitHub README itself.

License

ZStar is distributed under GPL-3.0.