xdatbus ======= .. py:module:: xdatbus Submodules ---------- .. toctree:: :maxdepth: 1 /api_reference/xdatbus/c01_xdc_aggregate/index /api_reference/xdatbus/c02a_xdc_unwrap/index /api_reference/xdatbus/c02b_xyz_unwarp/index /api_reference/xdatbus/c03_thermal_report/index /api_reference/xdatbus/c04_xml2xyz/index /api_reference/xdatbus/c05_sum_hills/index /api_reference/xdatbus/fcli/index /api_reference/xdatbus/fun_bld/index /api_reference/xdatbus/fun_com/index /api_reference/xdatbus/fun_mtd/index /api_reference/xdatbus/resources/index /api_reference/xdatbus/utils/index /api_reference/xdatbus/utils_bpy/index Attributes ---------- .. autoapisummary:: xdatbus.BPY_AVAILABLE xdatbus.PDB_AVAILABLE xdatbus.MN_AVAILABLE xdatbus.YAML_AVAILABLE Functions --------- .. autoapisummary:: xdatbus.update_folder xdatbus.remove_file xdatbus.filter_files xdatbus.xdc_aggregate xdatbus.main xdatbus.unwrap_pbc_dis xdatbus.xdc_unwrap xdatbus.main xdatbus.unwrap_pbc_dis xdatbus.xyz_unwrap xdatbus.filter_files xdatbus.thermal_report xdatbus.main xdatbus.filter_files xdatbus.xml2xyz xdatbus.main xdatbus.sum_hills xdatbus.main xdatbus.com_drift xdatbus.com_contcar xdatbus.gauss_pot_1d xdatbus.gauss_pot_2d xdatbus.gauss_pot_3d xdatbus.fes_1d xdatbus.fes_2d xdatbus.fes_3d xdatbus.hillspot2hills xdatbus.report_loader xdatbus.xdc2xtc xdatbus.reweight xdatbus.pmf_321 xdatbus.neb_2d xdatbus.local_minima xdatbus.read_lat_vec xdatbus.unwrap_pbc_dis xdatbus.update_folder xdatbus.remove_file xdatbus.skip_comments xdatbus.filter_files xdatbus.gauss_pot_1d xdatbus.gauss_pot_2d xdatbus.gauss_pot_3d xdatbus.realize_instances xdatbus.remove_nodes xdatbus.get_template_node xdatbus.set_color4element xdatbus.apply_yaml xdatbus.clear_scene xdatbus.render_image xdatbus.apply_modifiers_to_mesh xdatbus.yaml_gen xdatbus.yaml_loader xdatbus.main Package Contents ---------------- .. py:function:: update_folder(folder) Delete the folder and create a new one. Parameters ---------- folder : str The path of the folder .. py:function:: remove_file(file_path) Delete the file. Parameters ---------- file_path : str The path of the file .. py:function:: filter_files(files, pattern) .. py:function:: xdc_aggregate(xdc_dir='./', output_dir='./', del_temp=True, show_progress=False) Aggregate XDATCAR files from an AIMD simulation. Parameters ---------- xdc_dir : str (optional) Input path of the AIMD simulation, which contains the XDATCAR files output_dir : str (optional) Output path of the XDATBUS file del_temp : bool (optional) If ``False``, the intermediate folders will be deleted show_progress : bool (optional) Whether to show the progress bar .. py:function:: main() .. py:function:: unwrap_pbc_dis(coord_1, coord_2, box_length) Unwrap the distance between two coordinates. Parameters ---------- coord_1 : ndarray The first coordinate coord_2 : ndarray The second coordinate box_length : The length of the box Returns ------- float The unwrapped distance between the two coordinates .. py:function:: xdc_unwrap(xdc_path='./XDATBUS', output_path='./XDATBUS_unwrap.xyz', show_progress=False) Unwrap the coordinates in the XDATCAR file (to .xyz). Parameters ---------- xdc_path : str Input path of the XDATCAR file output_path : str Output path of the xyz file show_progress : bool (optional) Show the progress bar or not .. py:function:: main() .. py:function:: unwrap_pbc_dis(coord_1, coord_2, box_length) Unwrap the distance between two coordinates. Parameters ---------- coord_1 : ndarray The first coordinate coord_2 : ndarray The second coordinate box_length : The length of the box Returns ------- float The unwrapped distance between the two coordinates .. py:function:: xyz_unwrap(xyz_path, lattice) Unwrap the coordinates in the xyz file. The unwrapped coordinates will be written to a new xyz file. Parameters ---------- xyz_path : str Input path of the xyz file lattice : list Lattice vectors of the system .. py:function:: filter_files(files, pattern) .. py:function:: thermal_report(osz_dir='./', output_path='./', show_progress=False) Generate a thermal report from the OSZICAR files. Parameters ---------- osz_dir : str Input path of the OSZICAR files output_path : str Output path of the thermal report show_progress : bool Whether to show the progress bar .. py:function:: main() .. py:function:: filter_files(files, pattern) .. py:function:: xml2xyz(xml_dir='./', output_path='./', train_ratio=1.0, free_energy=True, show_progress=False) Convert the vasprun.xml files to extended xyz files. Parameters ---------- xml_dir : str Input path of the vasprun.xml files output_path : str Output path of the extended xyz files train_ratio : float (optional) The ratio of training set free_energy : bool (optional) Whether to keep the free energy from the xml files show_progress : bool (optional) Show the progress bar or not .. py:function:: main() .. py:function:: sum_hills(plumed_hills, plumed_outfile, plumed_min, plumed_max, plumed_bin, plumed_eachstep) .. py:function:: main() .. py:function:: com_drift(xyz_path, frame_start=0, frame_end=None, save_csv=True, timestep=1) Calculate the center of mass (COM) drift velocity for a xyz file. Parameters ---------- xyz_path : str Path to the XYZ file. frame_start : int The first frame to consider. frame_end : int The last frame to consider. If None, considers all frames. save_csv : bool Whether to save the COM to a csv file. timestep : int The time difference between each frame, in appropriate time units. Default is 1. Returns ------- np.ndarray The COM drift velocity, represented as a 3-element numpy array. .. py:function:: com_contcar(poscar_path, contcar_path, del_inter=False) Correct the CONTCAR file by adding the COM drift to the coordinates of the CONTCAR file. The COM drift is calculated by fcom01_drift(). Parameters ---------- poscar_path : str Path to the POSCAR path. contcar_path : str Path to the CONTCAR file. del_inter : bool Delete the intermediate files created by this function. .. py:function:: gauss_pot_1d(x: numpy.ndarray, x0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of positions at which to evaluate the potential. - x0 (float): The position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position x. .. py:function:: gauss_pot_2d(x: numpy.ndarray, y: numpy.ndarray, x0: float, y0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of x positions at which to evaluate the potential. - y (np.ndarray): Array of y positions at which to evaluate the potential. - x0 (float): The x position of the potential minimum. - y0 (float): The y position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position (x, y). .. py:function:: gauss_pot_3d(x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, x0: float, y0: float, z0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of x positions at which to evaluate the potential. - y (np.ndarray): Array of y positions at which to evaluate the potential. - z (np.ndarray): Array of z positions at which to evaluate the potential. - x0 (float): The x position of the potential minimum. - y0 (float): The y position of the potential minimum. - z0 (float): The z position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position (x, y, z). .. py:function:: fes_1d(hillspot_path, hills_count, cv_range, resolution=100) Calculate the 1D free energy profile from a HILLSPOT file. Parameters ---------- hillspot_path : str The path of the HILLSPOT file hills_count : int The number of hills to be read cv_range : list The range of the collective variable resolution : int (optional) The resolution of the free energy profile .. py:function:: fes_2d(hillspot_path, hills_count, cv_1_range, cv_2_range, resolution=100) Calculate the 2D free energy profile from a HILLSPOT file. Parameters ---------- hillspot_path : str The path of the HILLSPOT file hills_count : int The number of hills to be read cv_1_range : list The range of the first collective variable cv_2_range : list The range of the second collective variable resolution : int (optional) The resolution of the free energy profile .. py:function:: fes_3d(hillspot_path, hills_count, cv_1_range, cv_2_range, cv_3_range, resolution=100) Calculate the 2D free energy profile from a HILLSPOT file. Parameters ---------- hillspot_path : str The path of the HILLSPOT file hills_count : int The number of hills to be read cv_1_range : list The range of the first collective variable cv_2_range : list The range of the second collective variable cv_3_range : list The range of the third collective variable resolution : int (optional) The resolution of the free energy profile .. py:function:: hillspot2hills(hillspot_dir, hills_dir, cv, height_conversion=1, sigma_conversion=1, del_inter=False) Convert HILLSPOT file to HILLS file Parameters ---------- hillspot_dir : str Path to HILLSPOT file hills_dir : str Path to the directory where the HILLS file will be created cv : str or list Name of the collective variable(s) height_conversion : float(optional) Conversion factor to convert the unit of the height from eV to kJ/mol sigma_conversion : float(optional) Conversion factor to convert the unit of the sigma based on the lattice in Angstrom del_inter : bool(optional) Delete the intermediate files created by this function. .. py:function:: report_loader(aimd_path, load_pre_report=True, load_last_report=False, delete_intermediate_folders=True) Initialize a trajectory writer instance for *filename*. Parameters ---------- aimd_path : str Output filename of the trajectory; the extension determines the format. load_pre_report : bool (optional) If ``True``, the trajectory will contain the previous frames (before the current run) load_last_report : bool (optional) If ``True``, the trajectory will contain the last frame delete_intermediate_folders : bool (optional) If ``True``, the intermediate folders will be deleted .. py:function:: xdc2xtc(xdc_path) Convert a VASP XDATCAR file to an XTC trajectory file. Parameters ---------- xdc_path : str Path to the XDATCAR file .. py:function:: reweight(fes, cv, nv, kb, t, grid_min, grid_max, grid_num) Reweight a metadynamics simulation to the unbiased ensemble using histogram reweighting. In many cases you might decide which variable should be analyzed after having performed a metadynamics simulation. For example, you might want to calculate the free energy as a function of CVs other than those biased during the metadynamics simulation. At variance with standard MD simulations, you cannot simply calculate histograms of other variables directly from your metadynamics trajectory, because the presence of the metadynamics bias potential has altered the statistical weight of each frame. To remove the effect of this bias and thus be able to calculate properties of the system in the unbiased ensemble, you must reweight (unbias) your simulation. Parameters ---------- fes : np.ndarray The free energy surface calculated from the metadynamics simulation. cv : np.ndarray The collective variable used in the metadynamics simulation. nv : np.ndarray The new collective variable for which the potential of mean force will be calculated. kb : float The Boltzmann constant. t : float The temperature of the simulation. grid_min : float The minimum value of the collective variable. grid_max : float The maximum value of the collective variable. grid_num : int The number of bins in the histogram. Returns ------- np.ndarray The unbiased free energy surface. .. py:function:: pmf_321(fes3d, axis1, axis2) project 3d free energy surface to 1d Parameters ---------- fes3d : np.ndarray The 3d free energy surface. axis1 : int The axis to be projected. axis2 : int The axis to be projected. Returns ------- np.ndarray The 2d free energy surface. .. py:function:: neb_2d(fes, minima_1, minima_2, n_images, n_steps, spring_constant) .. py:function:: local_minima(data, size=3) .. py:function:: read_lat_vec(xdatcar_dir) Read the lattice vectors from the first image of the XDATCAR file. .. py:function:: unwrap_pbc_dis(coord_1, coord_2, box_length) Unwrap the distance between two coordinates. Parameters ---------- coord_1 : ndarray The first coordinate coord_2 : ndarray The second coordinate box_length : The length of the box Returns ------- float The unwrapped distance between the two coordinates .. py:function:: update_folder(folder) Delete the folder and create a new one. Parameters ---------- folder : str The path of the folder .. py:function:: remove_file(file_path) Delete the file. Parameters ---------- file_path : str The path of the file .. py:function:: skip_comments(file) .. py:function:: filter_files(files, pattern) .. py:function:: gauss_pot_1d(x: numpy.ndarray, x0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of positions at which to evaluate the potential. - x0 (float): The position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position x. .. py:function:: gauss_pot_2d(x: numpy.ndarray, y: numpy.ndarray, x0: float, y0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of x positions at which to evaluate the potential. - y (np.ndarray): Array of y positions at which to evaluate the potential. - x0 (float): The x position of the potential minimum. - y0 (float): The y position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position (x, y). .. py:function:: gauss_pot_3d(x: numpy.ndarray, y: numpy.ndarray, z: numpy.ndarray, x0: float, y0: float, z0: float, height: float, width: float) -> numpy.ndarray Calculate the Gaussian potential energy. Parameters: - x (np.ndarray): Array of x positions at which to evaluate the potential. - y (np.ndarray): Array of y positions at which to evaluate the potential. - z (np.ndarray): Array of z positions at which to evaluate the potential. - x0 (float): The x position of the potential minimum. - y0 (float): The y position of the potential minimum. - z0 (float): The z position of the potential minimum. - height (float): The height of the Gaussian potential. - width (float): The standard deviation (controls the width of the Gaussian). Returns: - np.ndarray: The potential energy at each position (x, y, z). .. py:data:: BPY_AVAILABLE :value: True .. py:data:: PDB_AVAILABLE :value: True .. py:data:: MN_AVAILABLE :value: True .. py:data:: YAML_AVAILABLE :value: True .. py:function:: realize_instances(obj, bond_radius) Realize instances of the given object. This function requires bpy. Parameters ---------- obj : bpy.types.Object The object to realize instances of bond_radius : float The radius of the bonds .. py:function:: remove_nodes(obj, node_names) Remove nodes with given names from the object's node tree. Parameters ---------- obj : bpy.types.Object The object from which to remove nodes. node_names : list of str The names of the nodes to remove. .. py:function:: get_template_node(node_name, nodes) Get a node from a template blend file. Parameters ---------- node_name : str The name of the node to get. nodes : bpy.types.NodeTree.nodes The nodes from the node tree to add the node to. Returns ------- node : bpy.types.Node The node from the template blend file. .. py:function:: set_color4element(obj, atomic_number, color, atomic_scale, bonded, bonded_count=0) Add a custom node and connect it to the specified input of the target node. Parameters ---------- obj : bpy.types.Object The object with the Geometry Nodes modifier whose node tree we're editing. atomic_number : int The atomic number of the element to set the color of. color : tuple The color to set the node to. atomic_scale : float The size of the atoms. bonded : bool Whether the atoms are bonded. bonded_count : int The number of elements forming a bond. .. py:function:: apply_yaml(obj, yaml_path) Set the color of the given object. This function requires bpy and molecularnodes. Parameters ---------- obj : bpy.types.Object The object to set the color of yaml_path : str The path to the YAML file to use .. py:function:: clear_scene(mesh=True, lights=True, geometry_nodes=True) Clear the scene of all objects. This function requires bpy. Parameters ---------- mesh : bool Clear mesh objects lights : bool Clear light objects geometry_nodes : bool Clear geometry node groups .. py:function:: render_image(engine='eevee', x=1000, y=500, output_path='render.png') Render an image. This function requires bpy. Parameters ---------- engine : str The render engine to use. Either 'eevee' or 'cycles' x : int The x resolution of the image y : int The y resolution of the image output_path : str The path to save the image to .. py:function:: apply_modifiers_to_mesh(obj) Apply modifiers to the given object. This function requires bpy. Parameters ---------- obj : bpy.types.Object The object to apply modifiers to .. py:function:: yaml_gen(pdb_file_path) This function generates a YAML file for the elements in the PDB file, with a common bond_radius. Parameters ---------- pdb_file_path : str Input path of the PDB file .. py:function:: yaml_loader(yaml_path) This function loads a YAML file and returns element data and bond radius. Parameters ---------- yaml_path : str Input path of the YAML file Returns ------- tuple A tuple containing a dictionary of elements with their properties and the common bond radius. .. py:function:: main()