{"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":"python","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":[{"wrong":"from castepxbin.pdos_bin import PdosBinReader","symbol":"read_pdos_bin","correct":"from castepxbin import read_pdos_bin"},{"symbol":"read_castep_bin","correct":"from castepxbin import read_castep_bin"},{"symbol":"read_ome_bin","correct":"from castepxbin import read_ome_bin"}],"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,"search_vec":"'0.3.1':58 'addit':68 'bin':38,42,47 'binari':2,14,76 'castep':1,19,41,72 'castepxbin':5 'check':53 'checkpoint':39 'chemistri':81 'code':26 'collect':8 'compat':70 'cst':49 'current':55 'data':31,78 'densiti':34 'dft':73 'driven':64 'element':45 'enabl':28 'featur':67 'file':3,16,40,77 'first':22 'first-principl':21 'fix':71 'function':52 'generat':17 'irregular':62 'like':32 'materi':74 'matrix':44 'mechan':25 'new':66 'occur':61 'ome':46,48 'optic':43 'output':15 'pars':29,79 'pdos':37 'primarili':63 'principl':23 'project':33 'python':10 'quantum':24,80 'reader':4,11 'releas':60 'scienc':75 'state':36 'various':13 'version':56 'wave':51","created_at":"2026-04-17T01:19:35.559900+00:00","updated_at":"2026-04-17T01:19:35.559900+00:00","problems":null,"ecosystem":"pypi","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":"0.3.1","cli_name":"","cli_version":null,"type":"library","homepage":null,"github":"https://github.com/zhubonan/castepxbin","docs":"https://zhubonan.github.io/castepxbin/","changelog":null,"pypi":"https://pypi.org/project/castepxbin/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null,"categories":["data","serialization"],"base_url":null,"auth_type":null,"provenance":{"verified_status":"passing","verified_at":"2026-06-30","last_verified":"2026-06-30","next_check":"2026-07-30","install_tag":null}}