CASTEP Binary File Readers

0.3.1 · active · verified Fri Apr 17

castepxbin is a collection of Python readers for various binary output files generated by CASTEP, a first-principles quantum mechanics code. It enables parsing of data like projected density of states (.pdos_bin), checkpoint files (.castep_bin), optical matrix elements (.ome_bin, .ome_cst), and wave functions (.check). The current version is 0.3.1, with releases occurring irregularly, primarily driven by new feature additions and compatibility fixes.

Common errors

```
FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.pdos_bin'
```
cause The specified CASTEP binary file does not exist at the provided path, or the path is incorrect.

fix Double-check the file path for typos, ensure the file is actually present, and confirm read permissions. Use an absolute path or verify the relative path from your script's execution location.
```
AttributeError: 'PdosBinReader' object has no attribute 'get_stress'
```
cause Attempting to access data (e.g., 'stress') that is not available or stored in the specific binary file type being read by that reader. For example, stress might be in `castep_bin` but not `pdos_bin`.

fix Consult the `castepxbin` documentation or the specific reader's methods to understand what data is available. Ensure you are using the correct reader for the file type containing the desired information (e.g., use `CastepBinReader` for stress if it's in the .castep_bin file).
```
DeprecationWarning: distutils.version.LooseVersion is deprecated. See https://peps.python.org/pep-0632/ For more information.
```
cause This warning, often related to `numpy`'s version parsing, indicates an older `castepxbin` version's dependency on deprecated parts of `distutils` when checking NumPy compatibility.

fix Upgrade to `castepxbin>=0.3.1`. This version includes fixes to avoid `DeprecationWarning` with newer NumPy versions (>=1.25) and Python environments.

Warnings

gotcha Older versions of `castepxbin` (pre-0.3.1) might encounter `DeprecationWarning` or unexpected behavior when used with NumPy versions 1.25.0 or newer due to changes in NumPy's C API.
Fix: Upgrade to `castepxbin>=0.3.1` to ensure full compatibility with modern NumPy versions (`pip install --upgrade castepxbin`).
gotcha Each reader class (`PdosBinReader`, `CastepBinReader`, etc.) is specific to a particular CASTEP binary file format. Using the wrong reader for a given file will likely lead to parsing errors or incorrect data.
Fix: Ensure you are using the correct reader class for the CASTEP binary file you are trying to parse (e.g., `PdosBinReader` for `.pdos_bin`, `CastepBinReader` for `.castep_bin`). Refer to the documentation for supported file types for each reader.
gotcha File paths must be exact and accessible. Relative paths are resolved from the current working directory.
Fix: Always verify that the file path provided to the reader constructor is correct and that the file exists at that location. Use `os.path.exists()` for debugging if encountering `FileNotFoundError`.

Install

pip install castepxbin Install stable version

Imports

PdosBinReader

from castepxbin.pdos_bin import PdosBinReader

CastepBinReader

from castepxbin.castep_bin import CastepBinReader

OmeBinReader

from castepxbin.ome_bin import OmeBinReader

CheckReader

wrong:

from castepxbin.check import CheckReader

correct:

from castepxbin.check_file import CheckReader

The check file reader is in 'check_file.py', not 'check.py'.

Quickstart

This quickstart demonstrates how to instantiate a `PdosBinReader` to read a CASTEP `.pdos_bin` file and access common data such as eigenvalues and projected density of states (PDOS) weights. Remember to replace 'path_to_your_castep.pdos_bin' with the actual path to your CASTEP output file. Similar patterns apply to `CastepBinReader`, `OmeBinReader`, and `CheckReader` for their respective file types.

import numpy as np
from castepxbin.pdos_bin import PdosBinReader

# Assuming you have a castep.pdos_bin file generated by CASTEP
# For demonstration, we'll create a dummy file. In a real scenario,
# this path would point to your actual CASTEP output.

dummy_pdos_data = {
    'kpoints': np.random.rand(5, 3), # Dummy k-points
    'num_spins': 1,
    'num_bands': 10,
    'num_species': 2,
    'num_proj_per_species': 9, # s, p_x, p_y, p_z, d_xy, d_yz, d_zx, d_x2y2, d_z2
    'eigenvalues': np.random.rand(1, 5, 10), # spin, kpoint, band
    'weights': np.random.rand(1, 5, 10, 2, 9), # spin, kpoint, band, species, projection
    'efermi': 0.0
}

# In a real scenario, you'd have a pdos_bin file.
# The library is for reading existing files, not creating them.
# This part is just to make the example runnable without an actual file.
# For a true quickstart, you'd replace 'path_to_your_file.pdos_bin' 
# with an actual file path.

# Example usage with a placeholder path:
file_path = 'path_to_your_castep.pdos_bin'

try:
    reader = PdosBinReader(file_path)
    # Access data, e.g., eigenvalues, weights
    eigenvalues = reader.get_eigenvalues()
    pdos_weights = reader.get_total_weights()

    print(f"Successfully read {file_path}")
    print(f"Eigenvalues shape: {eigenvalues.shape}")
    print(f"PDOS weights shape: {pdos_weights.shape}")

except FileNotFoundError:
    print(f"Error: The file '{file_path}' was not found. Please provide a valid CASTEP .pdos_bin file.")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →