Py4vasp

https://vasp.at/py4vasp/latest/
Admin
Py4vasp is a Python interface to extract, visualize, and post-process data from VASP calculations,...
Tokens:26,076
Snippets:191
Trust Score:9.6
Update:1 year ago
Show doc for...
Tokens:
Raw
### Install py4vasp using pip

Source: https://vasp.at/py4vasp/latest/index

Installs the py4vasp package and its dependencies from PyPI using the pip package installer. This is the standard method for installing py4vasp.

```bash
pip install py4vasp
```

--------------------------------

### Install py4vasp from GitHub

Source: https://vasp.at/py4vasp/latest/index

Clones the py4vasp repository from GitHub and installs it using pip. This method provides the latest version of the code with all bug fixes.

```bash
git clone https://github.com/vasp-dev/py4vasp.git
cd py4vasp
pip install .
```

--------------------------------

### Verify py4vasp installation

Source: https://vasp.at/py4vasp/latest/index

Runs a Python command to check if py4vasp is installed correctly by printing its version number. This is a quick test to confirm the installation.

```python
python -c "import py4vasp; print(py4vasp.__version__)"
```

--------------------------------

### Install py4vasp-core using pip

Source: https://vasp.at/py4vasp/latest/index

Installs the minimalistic py4vasp-core package, which includes only the essential functionalities and dependencies like numpy and h5py. This version is suitable for script developers who do not require visualization features.

```bash
pip install py4vasp-core
```

--------------------------------

### Create and Activate Virtual Environment

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Demonstrates how to create a Python virtual environment using `venv` and activate it on Linux/macOS and Windows. It then proceeds to install py4vasp within this isolated environment.

```bash
# Linux/MacOS:
python3 -m venv py4vasp-env
source py4vasp-env/bin/activate.sh

# Windows:
# py4vasp-env\Scripts\activate.bat

pip install py4vasp
```

--------------------------------

### Verify py4vasp Installation

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Verifies a successful installation of py4vasp by importing the library and printing its version number. This is a simple check to ensure the package is accessible in the Python environment.

```python
import py4vasp
print(py4vasp.__version__)
```

--------------------------------

### Create and Activate conda Environment

Source: https://vasp.at/py4vasp/latest/index

Creates a new conda environment named 'py4vasp-env' with Python installed and then activates it. This is recommended for managing dependencies, especially on Windows and macOS.

```bash
conda create --name py4vasp-env python
conda activate py4vasp-env
```

--------------------------------

### Complete Electronic Structure Analysis (Python)

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

An advanced workflow example demonstrating how to load a VASP calculation, extract and combine multiple properties (structure, energy, bandgap), export data to pandas DataFrames, save visualizations, and print summary statistics.

```python
from py4vasp import Calculation
import matplotlib.pyplot as plt

# Load calculation
calc = Calculation.from_path(".")

# Extract and combine multiple properties
structure = calc.structure.read()
energy = calc.energy.to_numpy()
bandgap_data = calc.bandgap.read()

# Export DOS and band structure
dos_df = calc.dos.to_frame(selection="d")
band_df = calc.band.to_frame(selection="d")

# Save visualizations
calc.structure.to_image(filename="structure.png")
calc.dos.to_image(selection="Ti(d), O(p)", filename="pdos.png")
calc.band.to_image(selection="d", filename="fatbands.png")

# Combine data for analysis
print(f"Bandgap: {bandgap_data['gap']:.3f} eV")
print(f"Final energy: {energy:.3f} eV")
print(f"Volume: {calc.structure.volume():.3f} Angstrom^3")
```

--------------------------------

### Get System Selections

Source: https://vasp.at/py4vasp/latest/calculation/system

Returns possible alternatives for a particular quantity VASP can produce. The output is a dictionary where the key is the quantity name and values are possible selections for other functions. This helps in choosing specific VASP outputs.

```python
system_instance.selections()
```

--------------------------------

### Access Calculation Steps for Trajectories

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Demonstrates how to access different ionic steps from VASP calculations involving molecular dynamics or relaxations. It shows how to get the final step, all steps, a specific step, or a range of steps.

```python
# Get final step (default behavior)
final_structure = calc.structure.read()

# Get all steps
all_structures = calc.structure[:].read()

# Get specific step
step_5 = calc.structure[5].read()

# Get range of steps
steps_1_to_6 = calc.structure[1:6].read()
```

--------------------------------

### Get Available Density Selections in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/density

Shows how to retrieve a dictionary of all possible densities and their components that VASP can produce, accessible via the `selections` method in py4vasp. This helps in understanding the available options for density and component selection in other functions.

```python
>>> calc = py4vasp.Calculation.from_path(".")
>>> available_selections = calc.density.selections()
>>> print(available_selections)
```

--------------------------------

### Get Available Selections

Source: https://vasp.at/py4vasp/latest/calculation/band

Retrieves a dictionary of possible selections for band structure quantities. This helps users understand the available options for filtering and analyzing projection data.

```python
>>> calc.projector.selections()
```

--------------------------------

### Read System Data

Source: https://vasp.at/py4vasp/latest/calculation/system

A convenient wrapper around to_dict for reading system data. It can accept various arguments to specify how the data should be read. Check to_dict for detailed examples and optional arguments.

```python
system_instance.read(*args, **kwargs)
```

--------------------------------

### Getting Available Structure Selections in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Demonstrates how to use the `selections()` method to discover the possible ways to select specific outputs from VASP calculations related to the structure. The returned dictionary maps quantity names to their selection options.

```python
selections() -> dict
```

--------------------------------

### Create Structures from External Sources - Python

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This section provides examples of creating py4vasp Structure objects from external data formats. It demonstrates creation from a POSCAR string and from an ASE Atoms object. The 'elements' argument is required when creating from POSCAR text.

```python
# Create from POSCAR string
poscar_text = """Sr Ti O
1.0
3.905 0.0 0.0
0.0 3.905 0.0
0.0 0.0 3.905
Sr Ti O
1 1 3
direct
0.0 0.0 0.0
0.5 0.5 0.5
0.5 0.5 0.0
0.5 0.0 0.5
0.0 0.5 0.5"""
structure = py4vasp.calculation.structure.Structure.from_POSCAR(
    poscar_text, elements=["Sr", "Ti", "O"])

# Create from ASE Atoms
from ase.build import bulk
atoms = bulk('Si', 'diamond', a=5.43)
structure = py4vasp.calculation.structure.Structure.from_ase(atoms)
```

--------------------------------

### Get Force Selections in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/force

Retrieves the possible selection options for force quantities in VASP output. The `selections()` method returns a dictionary where the key is the quantity name ('force') and the value is a list of all valid selection arguments.

```python
>>> calc.force.selections()
```

--------------------------------

### Get Available Orbital Projections

Source: https://vasp.at/py4vasp/latest/calculation/band

Retrieves a list of all available orbital projection selections. This is useful for understanding the valid syntax for selection strings used in other functions.

```python
>>> calc.projector.selections()

```

--------------------------------

### Get Ion Types as String

Source: https://vasp.at/py4vasp/latest/calculation/topology

Returns the type of all ions in the system as a string. This can be useful for identifying distinct atomic species.

```python
from py4vasp.calculation import Topology

topology = Topology.from_ase(atoms)
ion_types = topology.ion_types()
```

--------------------------------

### Get VASP Bandgap Information with py4vasp

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This code snippet demonstrates how to retrieve bandgap information from VASP calculations using py4vasp. It returns the bandgap value, the energy of the valence band maximum, and the energy of the conduction band minimum.

```python
# Get bandgap information
bandgap = calc.bandgap.read()
# Returns: {'gap': float, 'valence_band_maximum': float,
#           'conduction_band_minimum': float}
```

--------------------------------

### Export and Visualize DOS Data

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Provides functionalities to export Density of States (DOS) data into various formats and visualize it. This includes getting a list of available projections, exporting to CSV, converting to a pandas DataFrame, and saving as an image file.

```python
# Get list of all available projections
available = calc.projector.selections()
print(available)

# Export to CSV file
calc.dos.to_csv(selection="p", filename="dos_p_orbitals.csv")

# Export to pandas DataFrame for further processing
import pandas as pd
df = calc.dos.to_frame(selection="d")
print(df.head())

# Export as image
calc.dos.to_image(selection="Ti(d)", filename="ti_dos.png")
```

--------------------------------

### Initialize py4vasp Calculation from Path

Source: https://vasp.at/py4vasp/latest/index

Creates an instance of the py4vasp Calculation class, specifying the path to a VASP calculation directory. This allows managing access to input and output files for VASP calculations that are not in the current directory.

```python
from py4vasp import Calculation
calc = Calculation.from_path("/path/to/your/VASP/calculation")
```

--------------------------------

### Get Number of Atoms

Source: https://vasp.at/py4vasp/latest/calculation/topology

Returns the total number of atoms present in the crystal system. This provides a simple count of the atomic entities.

```python
from py4vasp.calculation import Topology

topology = Topology.from_ase(atoms)
num_atoms = topology.number_atoms()
```

--------------------------------

### Getting Number of Atoms in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Shows how to obtain the total number of atoms within the unit cell of a crystal structure using the Structure class in py4vasp.

```python
number_atoms() -> int
```

--------------------------------

### Projector Class Documentation

Source: https://vasp.at/py4vasp/latest/calculation/projector

Documentation for the Projector class, its constructor, and utility methods.

```APIDOC
## Projector Class

### Description
The projectors used for atom and orbital resolved quantities. This is a utility class that facilitates projecting quantities such as the electronic band structure and the DOS on atoms and orbitals. As a user, you can investigate the available projections with the `to_dict()` or `selections()` methods.

### Constructor
`_py4vasp.calculation._projector.Projector(_data_context_ , _** kwargs_)`

### Methods
#### `selections()`
Returns a list of all available projections.

**Example:**
```python
calc.projector.selections()
```

#### `parse_selection(_selection ='__all__'_)`
Generates all possible indices where the projected information is stored.

**Parameters:**
* **selection** (str) - A string specifying the projection of the orbitals. Possible values include atom names or indices, orbital types, and spin options (up, down, total). Multiple selections can be combined with commas, whitespace, or nested using parentheses. It also supports addition and subtraction of components. Deprecated since version 0.8.0.

**Yields:**
* Iterable[Index] - Indices of the atom, the orbital and the spin compatible with a specific selection.

#### `project(_selection_ , _projections_)`
Selects a certain subset of the given projections and returns them with a suitable label.

**Parameters:**
* **selection** (str) - A string specifying the projection of the orbitals. See `parse_selection` for detailed format.
* **projections** (np.ndarray) - A data array where the first three indices correspond to spin, atom, and orbital, respectively. The selection will be parsed and mapped onto the corresponding dimension.

#### `count(_value_ , _/_)`
Returns the number of occurrences of a value.

#### `index(_value_ , _start =0_, _stop =9223372036854775807_, _/_)`
Returns the first index of a value. Raises ValueError if the value is not present.

#### `print()`
Prints a string representation of this instance.
```

--------------------------------

### Create and Activate venv Environment (Linux/macOS)

Source: https://vasp.at/py4vasp/latest/index

Creates a Python virtual environment named 'py4vasp-env' using venv and activates it. This isolates project dependencies. The activation command needs to be run in each new shell session.

```bash
python3 -m venv py4vasp-env
source py4vasp-env/bin/activate.sh
```

--------------------------------

### Create and Activate venv Environment (Windows)

Source: https://vasp.at/py4vasp/latest/index

Creates a Python virtual environment named 'py4vasp-env' using venv and activates it. This isolates project dependencies. The activation command needs to be run in each new shell session.

```batch
python3 -m venv py4vasp-env
py4vasp-env\Scripts\activate.bat
```

--------------------------------

### Getting Lattice Vectors in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Demonstrates how to retrieve the lattice vectors that define the unit cell of a crystal structure using the Structure class in py4vasp. The output is provided in Angstroms.

```python
lattice_vectors() -> np.ndarray
```

--------------------------------

### Piezoelectric Tensor API

Source: https://vasp.at/py4vasp/latest/calculation/piezoelectric_tensor

This section covers the PiezoelectricTensor class, detailing its initialization, data retrieval methods, and utility functions.

```APIDOC
## PiezoelectricTensor Class

### Description
The `PiezoelectricTensor` class provides access to the piezoelectric tensor calculated by VASP. The piezoelectric tensor is the derivative of the energy with respect to strain and field, representing the coupling between mechanical stress and electrical polarization.

### Methods

- **`__init__(_data_context_, _**kwargs_)**
  Initializes the `PiezoelectricTensor` object.

- **`print()`**
  Prints a string representation of the `PiezoelectricTensor` instance.

- **`read(_*args_, _**kwargs_)`**
  A convenient wrapper around `to_dict`. Refer to `to_dict` for examples and optional arguments.

- **`selections()`**
  Returns possible alternatives for this particular quantity VASP can produce. The returned dictionary contains a single item with the name of the quantity mapping to all possible selections. Each of these selections may be passed to other functions of this quantity to select which output of VASP is used.
  **Returns:**
    dict - The key indicates this quantity and the values possible choices for arguments to other functions of this quantity.

- **`to_dict()`**
  Reads the ionic and electronic contributions to the piezoelectric tensor into a dictionary. It combines both terms as the total piezoelectric tensor (relaxed_ion) but also gives the pure electronic contribution, allowing separation of the parts.
  **Returns:**
    dict - The clamped ion and relaxed ion data for the piezoelectric tensor.

### Example Usage

```python
from py4vasp import calculation

# Assuming you have a VASP calculation context available
# For example:
# calc = calculation.Calculation("path/to/vasp/calculation") 
# piezo_tensor = calc.piezoelectric_tensor()

# Placeholder for demonstration purposes
class MockPiezoelectricTensor:
    def __init__(self):
        pass
    def to_dict(self):
        return {"clamped_ion": [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]], "relaxed_ion": [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]}
    def print(self):
        print("Mock PiezoelectricTensor instance")
    def selections(self):
        return {"piezoelectric_tensor": ["default"]}

piezo_tensor = MockPiezoelectricTensor()

# Print the instance
piezo_tensor.print()

# Get selections
print(piezo_tensor.selections())

# Get the data as a dictionary
tensor_data = piezo_tensor.to_dict()
print(tensor_data)

```
```

--------------------------------

### Getting Direct Positions in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Illustrates how to retrieve the direct (fractional) coordinates of all ions within the unit cell using the Structure class in py4vasp. These coordinates are dimensionless and relative to the lattice vectors.

```python
positions() -> np.ndarray
```

--------------------------------

### Index Class Documentation

Source: https://vasp.at/py4vasp/latest/calculation/projector

Documentation for the Index helper class used within Projector.

```APIDOC
## Index Class

### Description
Helper class specifying which atom, orbital, and spin are selected.

### Constructor
`_class _Index(_atom : str | Selection_, _orbital : str | Selection_, _spin : str | Selection_)`

### Attributes
* **atom** (str | Selection) - Label of the atom or a Selection object to read the corresponding data.
* **orbital** (str | Selection) - Label of the orbital or a Selection object to read the corresponding data.
* **spin** (str | Selection) - Label of the spin component or a Selection object to read the corresponding data.
```

--------------------------------

### Error Handling with py4vasp Exceptions (Python)

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Demonstrates how to handle common exceptions raised by py4vasp, such as `NoData`, `IncorrectUsage`, `FileAccessError`, and `OutdatedVaspVersion`. It also shows how to check for data existence before accessing it.

```python
import py4vasp
from py4vasp.exception import (
    NoData,
    IncorrectUsage,
    FileAccessError,
    OutdatedVaspVersion
)

try:
    calc = py4vasp.Calculation.from_path("/path/to/calculation")
    dos = calc.dos.read()
except FileAccessError as e:
    print(f"Cannot access HDF5 file: {e}")
except NoData as e:
    print(f"Data not available. Check INCAR flags: {e}")
except OutdatedVaspVersion as e:
    print(f"VASP version too old: {e}")
except IncorrectUsage as e:
    print(f"Incorrect usage: {e}")

# Check if data exists before accessing
if hasattr(calc, 'dos'):
    dos = calc.dos.read()
else:
    print("DOS data not available")
```

--------------------------------

### Getting Number of Trajectory Steps in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Explains how to find out the total number of structural steps (e.g., ionic relaxation steps or MD frames) available in a structure object within py4vasp.

```python
number_steps() -> int
```

--------------------------------

### Get Valence Band Maximum - py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/bandgap

Retrieves the valence band maximum values for all selected steps. Supports selecting specific steps or ranges of steps. Returns the data as a NumPy ndarray.

```python
>>> calc.bandgap.valence_band_maximum()
>>> calc.bandgap[:].valence_band_maximum()
>>> calc.bandgap[5].valence_band_maximum()
>>> calc.bandgap[1:6].valence_band_maximum()
```

--------------------------------

### Create py4vasp Calculation Instance from a Specific File

Source: https://vasp.at/py4vasp/latest/calculation/calculation

Shows how to initialize a py4vasp Calculation object by specifying a particular file containing VASP data. This method is useful when VASP output files are not in the default location or have non-default names, though `from_path` is generally preferred.

```python
from py4vasp import Calculation

# Example of using from_file (less common than from_path)
# Assuming 'OUTCAR.my_custom_name' is a VASP output file
calc_from_file = Calculation.from_file("OUTCAR.my_custom_name")

# Accessing data would then proceed similarly to from_path
# For example:
# print(calc_from_file.energy.read())

```

--------------------------------

### Print System Instance Representation

Source: https://vasp.at/py4vasp/latest/calculation/system

Prints a string representation of the System instance. This is useful for debugging and understanding the current state of the system object. No specific inputs are required.

```python
print(system_instance)
```

--------------------------------

### Reading Structure Data to Dictionary in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/structure

Explains the `read()` method as a convenient wrapper for `to_dict()`, used to convert structure data into a dictionary format in py4vasp. Refer to `to_dict()` for detailed examples and arguments.

```python
read(_* args_, _** kwargs_)
```

--------------------------------

### Visualize and Convert Structures - Python

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This snippet covers various methods for visualizing crystal structures and converting them between different formats using py4vasp. It includes in-browser 3D visualization (Jupyter), conversion to NGL widgets, POSCAR format, ASE Atoms objects, and MDTraj trajectories. Supercells can be applied for visualization.

```python
# Visualize in 3D (requires Jupyter)
calc.structure.to_view()

# Visualize with supercell
calc.structure.to_view(supercell=2)
calc.structure.to_view(supercell=[2, 2, 1])  # Asymmetric replication

# Convert to NGL widget
widget = calc.structure.to_ngl(supercell=2)

# Export to POSCAR format
poscar_string = calc.structure.to_POSCAR()
print(poscar_string)

# Get POSCAR for all steps
all_poscars = calc.structure[:].to_POSCAR()

# Convert to ASE Atoms object
atoms = calc.structure.to_ase()

# Convert to ASE with supercell
atoms_super = calc.structure.to_ase(supercell=2)

# Convert to mdtraj trajectory
import mdtraj
traj = calc.structure[:].to_mdtraj()
```

--------------------------------

### Get Conduction Band Minimum in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/bandgap

Retrieves the conduction band minimum (CBM) from VASP calculation results. The method supports reading CBM for the final step, all steps, specific steps, or a range of steps.

```python
>>> calc.bandgap.conduction_band_minimum()
>>> calc.bandgap[:].conduction_band_minimum()
>>> calc.bandgap[5].conduction_band_minimum()
>>> calc.bandgap[1:6].conduction_band_minimum()
```

--------------------------------

### selections() - Available Selection Options

Source: https://vasp.at/py4vasp/latest/calculation/projector

Returns a dictionary that details all available options for specifying atom, orbital, and spin selections within the VASP projection data.

```APIDOC
## GET /websites/vasp_at_py4vasp/selections

### Description
Retrieves a dictionary outlining the available options for specifying atom, orbital, and spin components for VASP projection data.

### Method
GET

### Endpoint
/websites/vasp_at_py4vasp/selections

### Response
#### Success Response (200)
- **dict** - A dictionary containing available selection options for spin, atom, and orbitals.

#### Response Example
```json
{
  "spin": {
    "options": ["up", "down", "total"],
    "default": "total"
  },
  "atom": {
    "options": ["Fe", "O", "__all__"],
    "default": "__all__"
  },
  "orbital": {
    "options": ["s", "pz", "dz2", "__all__"],
    "default": "__all__"
  }
}
```
```

--------------------------------

### Create Calculation Instance from Path

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

Creates an instance of the `Calculation` class from a specified VASP calculation directory. This object provides programmatic access to various properties of the calculation, such as structure, energy, and forces.

```python
from py4vasp import Calculation

calc = Calculation.from_path("/path/to/vasp/calculation")

# Access various properties
structure = calc.structure.read()
energy = calc.energy.read()
forces = calc.force.read()
```

--------------------------------

### Instantiate and Access VASP Calculation Data with py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/calculation

Demonstrates how to create a Calculation instance using `from_path` and access various VASP computed properties like density of states, magnetism, and structure. This is the primary method for loading VASP data into py4vasp.

```python
from py4vasp import Calculation

calc = Calculation.from_path("path_to_your_calculation")
calc.dos.plot()         # to plot the density of states
calc.magnetism.read()   # to read the magnetic moments
calc.structure.print()  # to print the structure in a POSCAR format
```

--------------------------------

### Energy Visualization

Source: https://vasp.at/py4vasp/latest/calculation/energy

Methods for visualizing energy data from VASP calculations, including generating graphs and saving them to image files.

```APIDOC
## GET /websites/vasp_at_py4vasp/energy

### Description
Accesses energy data from VASP calculations. The results depend on the selected steps using array slicing.

### Method
GET

### Endpoint
/websites/vasp_at_py4vasp/energy

### Parameters
#### Path Parameters
None

#### Query Parameters
* **step_selection** (string) - Optional - Specifies the steps to retrieve energy data for (e.g., `5`, `1:6`, `[:]` for all steps, or empty for the final step).

### Request Example
```json
{
  "step_selection": "1:6"
}
```

### Response
#### Success Response (200)
- **energy_data** (object) - Contains energy data, can be a graph, numpy array, or plotly figure depending on the method called.

#### Response Example
```json
{
  "energy_data": "..."
}
```

## POST /websites/vasp_at_py4vasp/energy/to_graph

### Description
Generates a graph of the energy data for the selected steps.

### Method
POST

### Endpoint
/websites/vasp_at_py4vasp/energy/to_graph

### Parameters
#### Path Parameters
None

#### Query Parameters
* **step_selection** (string) - Optional - Specifies the steps to generate the graph for (e.g., `5`, `1:6`, `[:]` for all steps, or empty for the final step).

#### Request Body
None (arguments are passed to the `to_graph()` function)

### Request Example
```json
{
  "step_selection": ":"
}
```

### Response
#### Success Response (200)
- **graph_data** (object) - Data representing the energy graph.

#### Response Example
```json
{
  "graph_data": "..."
}
```

## POST /websites/vasp_at_py4vasp/energy/to_image

### Description
Reads the energy data and generates an image file.

### Method
POST

### Endpoint
/websites/vasp_at_py4vasp/energy/to_image

### Parameters
#### Path Parameters
None

#### Query Parameters
* **step_selection** (string) - Optional - Specifies the steps to generate the image for (e.g., `5`, `1:6`, `[:]` for all steps, or empty for the final step).
* **filename** (string) - Required - The name of the output image file (e.g., "energy_plot.png").
* **format** (string) - Optional - The file format (e.g., png, jpg, svg, pdf). Deduced from filename if not provided.

#### Request Body
None (arguments are passed to the `to_graph()` function)

### Request Example
```json
{
  "step_selection": "[:",
  "filename": "vasp_energy.svg"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the image has been generated.

#### Response Example
```json
{
  "message": "Image saved to vasp_energy.svg"
}
```

## GET /websites/vasp_at_py4vasp/energy/to_numpy

### Description
Reads the energy of the selected steps and returns it as a NumPy array or a float.

### Method
GET

### Endpoint
/websites/vasp_at_py4vasp/energy/to_numpy

### Parameters
#### Path Parameters
None

#### Query Parameters
* **selection** (string) - Optional - Labels of the energy to be read (e.g., 'TOTEN', 'EKIN'). Defaults to 'TOTEN'. Can be a comma-separated string or an expression like 'TOTEN + EKIN'.
* **step_selection** (string) - Optional - Specifies the steps to retrieve energy data for (e.g., `5`, `1:6`, `[:]` for all steps, or empty for the final step).

### Request Example
```json
{
  "selection": "TOTEN + EKIN",
  "step_selection": "1:5"
}
```

### Response
#### Success Response (200)
- **energy_values** (float or np.ndarray or tuple) - Contains energies associated with the selection for the selected ionic step(s).

#### Response Example
```json
{
  "energy_values": [1.0, 2.5, 3.1]
}
```

## POST /websites/vasp_at_py4vasp/energy/to_plotly

### Description
Converts the energy graph to a Plotly figure.

### Method
POST

### Endpoint
/websites/vasp_at_py4vasp/energy/to_plotly

### Parameters
#### Path Parameters
None

#### Query Parameters
* **step_selection** (string) - Optional - Specifies the steps to convert to a Plotly figure (e.g., `5`, `1:6`, `[:]` for all steps, or empty for the final step).

#### Request Body
None (arguments are passed to the `to_graph()` function)

### Request Example
```json
{
  "step_selection": ":"
}
```

### Response
#### Success Response (200)
- **plotly_figure** (object) - Data representing the Plotly figure.

#### Response Example
```json
{
  "plotly_figure": "..."
}
```
```

--------------------------------

### Access and Select Density Components in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/density

Demonstrates how to access density data and select specific components using py4vasp. It shows the use of the `to_dict` method for retrieving density information and the `plot` method for visualization with various selection options, including aliases and nested component specifications.

```python
>>> calc = py4vasp.Calculation.from_path(".")
>>> calc.density.to_dict("n")
>>> calc.density.plot("magnetization")
Using synonyms and nesting
>>> calc.density.plot("n m(1,2) mag(sigma_z)")
```

--------------------------------

### Generate Band Structure Graph

Source: https://vasp.at/py4vasp/latest/calculation/band

Generates a graph of the band structure, optionally with orbital projections visualized as band widths. The 'selection' parameter uses a powerful string syntax to specify atoms, orbitals, spin, and k-point meshes.

```python
>>> calc.band.to_graph(selection="1(p)")

```

```python
>>> calc.band.to_graph("d(Mn, Co, Fe)")

```

```python
>>> calc.band.to_graph("up(1:3)")

```

```python
>>> calc.band.to_graph("dxy + dxz + dyz")

```

--------------------------------

### Accessing Partial Charge Data with py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/partial_charge

This snippet demonstrates how to use the PartialCharge class to access and process partial charge density data. It covers retrieving specific band and k-point contributions, converting data to a NumPy array, and generating an STM image.

```python
from py4vasp.calculation import PartialCharge

# Assuming 'pc' is an instance of PartialCharge
pc = PartialCharge.read("path/to/vasprun.xml") # Or from_dict, etc.

# Get the partial charge density as a 3D NumPy array for total spin, summing all bands and k-points
charge_density_total = pc.to_numpy()

# Get the partial charge density for spin-up, for a specific band (e.g., the 3rd band) and k-point (e.g., the 1st k-point)
charge_density_up_specific = pc.to_numpy(selection="up", band=2, kpoint=0)

# Generate an STM image in constant height mode
stm_image = pc.to_stm(selection="constant_height", tip_height=2.5)

# Print the dictionary representation of partial charges
print(pc.to_dict())

# Get contributing bands and k-points
contributing_bands = pc.bands()
contributing_kpoints = pc.kpoints()

print(f"Contributing bands: {contributing_bands}")
print(f"Contributing k-points: {contributing_kpoints}")
```

--------------------------------

### Convert VASP Density to NGL Widget with py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/density

Converts a VASP density view to an NGL widget for interactive visualization. This method wraps the `to_view()` method and accepts all its arguments. The resulting widget displays the structure and other quantities within the unit cell.

```python
>>> calc.density.to_ngl(a=0.3, normal="x")
```

--------------------------------

### Read VASP Phonon Band Structure with py4vasp

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This snippet demonstrates reading and plotting phonon band structures from VASP calculations using py4vasp. It covers reading the band structure data, which includes q-point distances, frequencies, modes, and labels, and then visualizing it.

```python
from py4vasp import Calculation
calc = Calculation.from_path(".")

# Read phonon band structure
phonon_bands = calc.phonon_band.read()
# Returns: {'qpoint_distances': array([...]), 'frequencies': array([...]),
#           'modes': array([[...]]), 'labels': [...]} 

# Plot phonon bands
calc.phonon_band.plot()
```

--------------------------------

### Workfunction Class Methods

Source: https://vasp.at/py4vasp/latest/calculation/workfunction

This section details the methods available for the Workfunction class, which describes the energy required to remove an electron to the vacuum.

```APIDOC
## Workfunction Class Methods

### Description
Provides functionality to analyze the workfunction computed by VASP.

### Methods

- **`plot(*args, **kwargs)`**: Wrapper around the `to_graph()` function. Merges multiple graphs if different sources are specified.
- **`print()`**: Prints a string representation of the instance.
- **`read(*args, **kwargs)`**: Convenient wrapper around `to_dict`.
- **`selections()`**: Returns possible alternatives for the workfunction quantity that VASP can produce.
- **`to_csv(*args, filename=None, **kwargs)`**: Converts data to a CSV file.
- **`to_dict()`**: Reports information about the workfunction as a dictionary, including vacuum potential, valence band maximum, conduction band minimum, and Fermi energy.
- **`to_frame(*args, **kwargs)`**: Generates dataframes from the graph object.
- **`to_graph()`**: Plots the average potential along the lattice vector selected by IDIPOL.
- **`to_image(*args, filename=None, **kwargs)`**: Reads data and generates an image file.
- **`to_plotly(*args, **kwargs)`**: Converts the graph of this quantity to a Plotly figure.

### Parameters

- **`filename`** (_str_ | _Path_) - Optional - Name of the CSV file for `to_csv` or image file for `to_image`.

### Return Types

- **`plot()`**: Returns merged graphs.
- **`read()`**: Returns dictionary representation of the data.
- **`selections()`**: Returns a dictionary with the quantity name mapping to possible selections.
- **`to_csv()`**: Writes data to a CSV file.
- **`to_dict()`**: Returns a dictionary containing vacuum potential, average potential, and relevant reference energies.
- **`to_frame()`**: Returns a Pandas DataFrame.
- **`to_graph()`**: Returns a graph object.
- **`to_image()`**: Writes data to an image file.
- **`to_plotly()`**: Returns a Plotly figure.

### Examples

#### Reading Workfunction Data
```python
from py4vasp import Workfunction

# Assuming 'wf' is an instance of Workfunction
# wf = Workfunction(...) 

data_dict = wf.to_dict()
print(data_dict)
```

#### Saving Workfunction Data to CSV
```python
# Assuming 'wf' is an instance of Workfunction
# wf.to_csv(filename='workfunction_data.csv') 
```

#### Plotting Workfunction
```python
# Assuming 'wf' is an instance of Workfunction
# graph = wf.to_graph()
# graph.show() # or other plotting library methods
```
```

--------------------------------

### Visualize VASP Density Data with py4vasp

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This snippet shows how to visualize density data from VASP calculations using py4vasp. It covers plotting charge density isosurfaces, magnetization, specific components with custom isolevels, and converting density visualizations to NGL widgets for interactive exploration.

```python
# Plot charge density isosurface (requires Jupyter)
calc.density.plot()

# Plot magnetization
calc.density.plot("magnetization")

# Plot specific component with custom isolevel
calc.density.to_view("charge", isolevel=0.5)

# Plot with supercell
calc.density.to_view("m(3)", supercell=2)

# Convert to NGL widget
widget = calc.density.to_ngl("magnetization")
```

--------------------------------

### Create Topology from ASE Atoms Object

Source: https://vasp.at/py4vasp/latest/calculation/topology

Generates a py4vasp Topology object from an ASE Atoms object. This is useful for integrating py4vasp with existing ASE-based workflows.

```python
from py4vasp.calculation import Topology

# Assuming 'atoms' is an ASE Atoms object
topology = Topology.from_ase(atoms)
```

--------------------------------

### Visualize Forces in py4vasp

Source: https://vasp.at/py4vasp/latest/calculation/force

Visualizes atomic forces using arrows overlaid on the crystal structure. Supports displaying forces for the entire trajectory or specific steps. The `to_view()` method generates a visual representation, and `to_ngl()` converts it to an NGL widget for interactive display.

```python
>>> calc.force.to_view()
>>> calc.force[:].to_view()
>>> calc.force[5].to_view()
>>> calc.force[1:6].to_view()
>>> calc.force.to_ngl()
```

--------------------------------

### Convert System to Dictionary

Source: https://vasp.at/py4vasp/latest/calculation/system

Returns a dictionary containing the system tag. This method is useful for serializing the system object or for further processing of the system data in dictionary format.

```python
system_instance.to_dict()
```

--------------------------------

### Topology Class Methods

Source: https://vasp.at/py4vasp/latest/calculation/topology

This section details the various methods available within the Topology class for extracting and manipulating crystal structure information.

```APIDOC
## Topology Class Methods

### Description
Methods for interacting with crystal topology data, including extracting atom information, converting to different formats, and generating POSCAR strings.

### Methods

- **elements()**
  - **Description**: Extracts the element of all atoms in the crystal.
  - **Returns**: List of element symbols.

- **ion_types()**
  - **Description**: Returns the type of all ions in the system as strings.
  - **Returns**: List of ion type strings.

- **names()**
  - **Description**: Extracts the labels (names) of all atoms in the crystal.
  - **Returns**: List of atom labels.

- **number_atoms()**
  - **Description**: Returns the total number of atoms in the system.
  - **Returns**: Integer representing the atom count.

- **read(\*args, \*\*kwargs)**
  - **Description**: A convenient wrapper around `to_dict()` for reading topology data. It ensures proper data conversion and validation.
  - **Parameters**: Accepts arbitrary arguments and keyword arguments passed to `to_dict()`.
  - **Returns**: Dictionary representation of the topology.

- **selections()**
  - **Description**: Returns possible alternatives for a specific quantity that VASP can produce, used for selecting specific VASP outputs.
  - **Returns**: A dictionary where the key is the quantity name and values are possible choices for arguments to other functions of this quantity.

- **to_POSCAR(format_newline='')**
  - **Description**: Generates the topology lines for a POSCAR file.
  - **Parameters**:
    - **format_newline** (str) - Optional string for custom formatting of the POSCAR output.
  - **Returns**: A string formatted for the POSCAR file.

- **to_dict()**
  - **Description**: Reads the topology and converts it into a dictionary format. This dictionary maps labels to atom indices and provides element-wise and index-based lookups.
  - **Returns**: A dictionary containing topology information.

- **to_frame()**
  - **Description**: Converts the topology data into a pandas DataFrame, matching atom labels with their element types.
  - **Returns**: A pandas DataFrame.

- **to_mdtraj()**
  - **Description**: Converts the topology data into an `mdtraj.Topology` object.
  - **Returns**: An `mdtraj.Topology` object.

### Class Methods

- **_from_ase(_structure_)**
  - **Description**: Generates a `Topology` object from a given `ase.Atoms` object.
  - **Parameters**:
    - **_structure_** (`ase.Atoms`) - The ASE Atoms object to convert.
  - **Returns**: A `Topology` object.
```

--------------------------------

### Convert View to NGL Widget (Python)

Source: https://vasp.at/py4vasp/latest/calculation/magnetism

Converts a View object, representing VASP calculation data, into an NGL widget for visualization. This method wraps the `to_view()` method and inherits its arguments. The returned widget displays structure and other quantities within the unit cell.

```python
>>> # Assuming 'calc' is a VASP calculation object
>>> # The actual NGLWidget object would be returned here.
```

--------------------------------

### Convert structure to NGL widget

Source: https://vasp.at/py4vasp/latest/calculation/structure

Converts the structure visualization to an NGL widget for interactive display within environments like Jupyter notebooks. This method wraps the `to_view()` method and inherits its arguments.

```python
>>> calc.structure.to_ngl(*args, **kwargs)
```

--------------------------------

### Read VASP Phonon Density of States with py4vasp

Source: https://context7.com/context7/vasp_at_py4vasp/llms.txt

This section shows how to read and plot the phonon density of states (DOS) from VASP calculations using py4vasp. It covers reading the DOS data, which includes energies and DOS values, and then visualizing the plot.

```python
from py4vasp import Calculation
calc = Calculation.from_path(".")

# Read phonon DOS
phonon_dos = calc.phonon_dos.read()
# Returns: {'energies': array([...]), 'dos': array([...])}

# Plot phonon DOS
calc.phonon_dos.plot()
```
Tokens:
Raw