{"id":9572,"library":"castepxbin","title":"CASTEP Binary File Readers","description":"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.","status":"active","version":"0.3.1","language":"en","source_language":"en","source_url":"https://github.com/zhubonan/castepxbin","tags":["CASTEP","DFT","materials science","binary files","data parsing","quantum chemistry"],"install":[{"cmd":"pip install castepxbin","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core dependency for array manipulation and data handling from binary files.","package":"numpy"}],"imports":[{"symbol":"PdosBinReader","correct":"from castepxbin.pdos_bin import PdosBinReader"},{"symbol":"CastepBinReader","correct":"from castepxbin.castep_bin import CastepBinReader"},{"symbol":"OmeBinReader","correct":"from castepxbin.ome_bin import OmeBinReader"},{"note":"The check file reader is in 'check_file.py', not 'check.py'.","wrong":"from castepxbin.check import CheckReader","symbol":"CheckReader","correct":"from castepxbin.check_file import CheckReader"}],"quickstart":{"code":"import numpy as np\nfrom castepxbin.pdos_bin import PdosBinReader\n\n# Assuming you have a castep.pdos_bin file generated by CASTEP\n# For demonstration, we'll create a dummy file. In a real scenario,\n# this path would point to your actual CASTEP output.\n\ndummy_pdos_data = {\n    'kpoints': np.random.rand(5, 3), # Dummy k-points\n    'num_spins': 1,\n    'num_bands': 10,\n    'num_species': 2,\n    'num_proj_per_species': 9, # s, p_x, p_y, p_z, d_xy, d_yz, d_zx, d_x2y2, d_z2\n    'eigenvalues': np.random.rand(1, 5, 10), # spin, kpoint, band\n    'weights': np.random.rand(1, 5, 10, 2, 9), # spin, kpoint, band, species, projection\n    'efermi': 0.0\n}\n\n# In a real scenario, you'd have a pdos_bin file.\n# The library is for reading existing files, not creating them.\n# This part is just to make the example runnable without an actual file.\n# For a true quickstart, you'd replace 'path_to_your_file.pdos_bin' \n# with an actual file path.\n\n# Example usage with a placeholder path:\nfile_path = 'path_to_your_castep.pdos_bin'\n\ntry:\n    reader = PdosBinReader(file_path)\n    # Access data, e.g., eigenvalues, weights\n    eigenvalues = reader.get_eigenvalues()\n    pdos_weights = reader.get_total_weights()\n\n    print(f\"Successfully read {file_path}\")\n    print(f\"Eigenvalues shape: {eigenvalues.shape}\")\n    print(f\"PDOS weights shape: {pdos_weights.shape}\")\n\nexcept FileNotFoundError:\n    print(f\"Error: The file '{file_path}' was not found. Please provide a valid CASTEP .pdos_bin file.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to `castepxbin>=0.3.1` to ensure full compatibility with modern NumPy versions (`pip install --upgrade castepxbin`).","message":"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.","severity":"gotcha","affected_versions":"<0.3.1"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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`.","message":"File paths must be exact and accessible. Relative paths are resolved from the current working directory.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"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.","cause":"The specified CASTEP binary file does not exist at the provided path, or the path is incorrect.","error":"FileNotFoundError: [Errno 2] No such file or directory: 'non_existent_file.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).","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`.","error":"AttributeError: 'PdosBinReader' object has no attribute 'get_stress'"},{"fix":"Upgrade to `castepxbin>=0.3.1`. This version includes fixes to avoid `DeprecationWarning` with newer NumPy versions (>=1.25) and Python environments.","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.","error":"DeprecationWarning: distutils.version.LooseVersion is deprecated. See https://peps.python.org/pep-0632/ For more information."}]}