MBN-tools 0.1__tar.gz → 1.0.0__tar.gz

mbn_tools-1.0.0/LICENSE.txt

@@ -0,0 +1,7 @@
+Copyright 2024, MBN-tools Developers.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

mbn_tools-1.0.0/MBN_tools/__init__.py

@@ -0,0 +1,66 @@
+"""
+MBN Tools
+
+A collection of functions for use with the MBN Explorer software (https://mbnresearch.com/get-mbn-explorer-software).
+
+This module includes functions for:
+- Running MBN Explorer simulations.
+- File manipulation.
+- Data analysis.
+- Visualisation.
+
+Dependencies:
+- numpy
+- scipy
+- mdtraj
+- vispy
+
+Example:
+    import MBN_tools as MBN
+
+    # Run MBN Explorer simulation
+    stdout, stderr = MBN.run_MBN('task_file.task', '/path/to/MBN_Explorer')
+
+    # Read XYZ file
+    xyz_data = MBN.read_xyz('xyz_file.xyz')
+"""
+
+
+from .core import (
+    create_structured_array,
+    run_task,
+    read_task,
+    write_task,
+    read_xyz,
+    write_xyz,
+    read_trajectory,
+    xyz_to_pdb,
+    xyz_to_input
+)
+
+from . import analysis
+from . import crystallography
+from . import visualise
+
+
+__all__ = [
+    # Core functions
+    'create_structured_array',
+    'run_task',
+    'read_task',
+    'write_task',
+    'read_xyz',
+    'write_xyz',
+    'read_trajectory',
+    'xyz_to_pdb',
+    'xyz_to_input',
+
+    # Submodules
+    'analysis',
+    'crystallography',
+    'visualise',
+]
+
+
+def __dir__():
+    return __all__

mbn_tools-1.0.0/MBN_tools/analysis.py

@@ -0,0 +1,227 @@
+"""
+Analysis submodule of MBN_tools.
+Provides utility functions for MBN Explorer trajectory file analysis.
+
+Functions:
+- calculate_rdf
+- calculate_msd
+- calculate_rmsd
+
+Example:
+    import MBN_tools as MBN
+    from MBN_tools import analysis
+
+    xyz_data = MBN.read_xyz('xyz_file.xyz')
+    RMSD = analysis.calculate_rmsd(xyz_data, box_size=[50, 50, 100], directions='xyz')
+"""
+
+import warnings
+import numpy as np
+from scipy.spatial import KDTree
+from typing import Optional, Tuple
+
+def calculate_rdf(coordinates: np.ndarray, step: float, r_max: float, frame: int = 0, box_size: Optional[np.ndarray] = None, select_atoms: Optional[str] = None) -> Tuple[np.ndarray, np.ndarray]:
+    """
+    Calculate the radial distribution function (RDF) from coordinates.
+
+    Parameters:
+        coordinates (numpy.ndarray): A structured array of coordinates.
+        step (float): The width of the bins for RDF calculation.
+        r_max (float): The maximum distance for RDF calculation.
+        frame (int, optional): The simulation frame to use if specified. Defaults to the first frame.
+        box_size (numpy.ndarray, optional): Dimensions of the simulation box. If None, it will be calculated from coordinates.
+        select_atoms (str, optional): Atom type to select. Default is None.
+
+    Returns:
+        tuple: (r_values, rdf) where r_values is an array of bin centers and rdf is the radial distribution function.
+    """
+
+    coordinates = coordinates[frame]
+    if box_size is None:
+        # Calculate box dimensions from given coors
+        mins = np.min(coordinates['coordinates'], axis=0)
+        maxs = np.max(coordinates['coordinates'], axis=0)
+        box_size = maxs - mins
+        warnings.warn('Using calculated box size. This is unadvisable and may produce incorrect results. For best results define a box size manually.')
+
+    if select_atoms:
+        # Reduce coordinates to selection of atom types
+        coordinates = coordinates[np.isin(coordinates['atoms'], select_atoms)]
+        if len(coordinates) == 0:
+            raise ValueError('No atoms of the selected type(s).')
+
+    num_atoms = len(coordinates)
+    num_bins = int(r_max / step)
+    
+    rdf = np.zeros(num_bins)
+    
+    # Apply PBC for coordinates
+    pbc_coordinates = coordinates['coordinates'] % box_size
+    
+    # Create KD-tree
+    tree = KDTree(pbc_coordinates)
+    
+    # Average density rho for cuboidal box
+    box_volume = np.prod(box_size)
+    density = num_atoms / box_volume
+    
+    # Find pairs within max_distance using KD-tree
+    pairs = tree.query_pairs(r=r_max, output_type='ndarray')
+    
+    # Calculate distances and bin them
+    distances = np.linalg.norm(pbc_coordinates[pairs[:, 0]] - pbc_coordinates[pairs[:, 1]], axis=1)
+    hist, bin_edges = np.histogram(distances, bins=num_bins, range=(0, r_max))
+    
+    r_values = (bin_edges[:-1] + bin_edges[1:]) / 2  # Mid points of bins
+    
+    # Convert histogram to RDF
+    for i_bin in range(num_bins):
+        r = r_values[i_bin]
+        shell_volume = 4 * np.pi * r**2 * step
+        rdf[i_bin] = hist[i_bin] / (shell_volume * density * num_atoms)
+
+    return r_values, rdf
+
+
+def calculate_msd(structured_array, box_size, directions='xyz'):
+    """
+    Calculate the Mean Squared Displacement (MSD).
+    
+    Parameters:
+        structured_array (np.ndarray): A structured array of coordinates.
+        box_size (float or list): Size of the simulation box. A single float assumes a cubic box, 
+                                  and a list of three values specifies [Lx, Ly, Lz] for non-cubic boxes.
+        directions (str): Directions to include in the MSD calculation ('x', 'y', 'z', or combinations like 'xyz', 'xy', etc.).
+    
+    Returns:
+        np.ndarray: MSD values as a function of time.
+    """
+    # Extract coordinates
+    coordinates = structured_array['coordinates']  # Shape: (n_timesteps, n_atoms, 3)
+    n_timesteps, n_atoms, _ = coordinates.shape
+
+    # Handle box size
+    if isinstance(box_size, (int, float)):
+        box_size = np.array([box_size] * 3)  # Convert to cubic box
+    else:
+        box_size = np.array(box_size)  # Ensure array format
+
+    if box_size.shape != (3,):
+        raise ValueError("Box size must be a single value for cubic boxes or a list of three values for non-cubic boxes.")
+
+    # Calculate displacements
+    displacements = np.zeros_like(coordinates)
+    for t in range(1, n_timesteps):
+        step_displacement = coordinates[t] - coordinates[t - 1]
+        # Apply minimum image convention for PBC
+        step_displacement -= box_size * np.round(step_displacement / box_size)
+        displacements[t] = displacements[t - 1] + step_displacement
+
+    # Initial positions
+    initial_positions = displacements[0]  # Shape: (n_atoms, 3)
+
+    # Total displacements
+    total_displacements = displacements - initial_positions  # Shape: (n_timesteps, n_atoms, 3)
+
+    # Filter for specified directions
+    direction_indices = {'x': 0, 'y': 1, 'z': 2}
+    selected_indices = [direction_indices[dim] for dim in directions]
+    selected_displacements = total_displacements[..., selected_indices]  # Select desired dimensions
+
+    # Squared displacements
+    squared_displacements = np.sum(selected_displacements**2, axis=-1)  # Sum over selected dimensions
+
+    # Mean squared displacement (MSD) over all atoms
+    msd = np.mean(squared_displacements, axis=1)  # Average over particles
+
+    return msd
+
+
+def calculate_rmsd(structured_array, box_size, directions='xyz'):
+    """
+    Calculate the Root Mean Squared Displacement (RMSD),
+    handling periodic boundary conditions (PBC).
+
+    Parameters:
+        structured_array (np.ndarray): A structured array of coordinates.
+        box_size (float or list): Size of the simulation box. A single float assumes a cubic box,
+                                  and a list of three values specifies [Lx, Ly, Lz] for non-cubic boxes.
+        directions (str): Directions to include in the displacement calculation ('x', 'y', 'z', or combinations like 'xyz', 'xy', etc.).
+
+    Returns:
+        np.ndarray: RMSD values as a function of time.
+    """
+    # Compute MSD first
+    msd = calculate_msd(structured_array, box_size, directions=directions)
+
+    # Compute RMSD
+    rmsd = np.sqrt(msd)
+
+    return rmsd
+
+
+def melting_temperature_calculation() -> None:
+    """
+    Placeholder function for melting temperature calculation.
+
+    Returns:
+        None
+    """
+    
+    pass
+
+
+def diffusion_analysis() -> None:
+    """
+    Placeholder function for diffusion analysis.
+
+    Returns:
+        None
+    """
+    
+    pass
+
+
+def kinetic_energy_distribution() -> None:
+    """
+    Placeholder function for kinetic energy distribution analysis.
+
+    Returns:
+        None
+    """
+    
+    pass
+
+
+def temperature_fluctuation_calculation() -> None:
+    """
+    Placeholder function for temperature fluctuation calculation.
+
+    Returns:
+        None
+    """
+    
+    pass
+
+
+def heat_capacity_calculation() -> None:
+    """
+    Placeholder function for heat capacity calculation.
+
+    Returns:
+        None
+    """
+    
+    pass
+
+
+def spectral_statistics_analyser() -> None:
+    """
+    Placeholder function for spectral statistics analysis.
+
+    Returns:
+        None
+    """
+    
+    pass
+

mbn_tools-1.0.0/MBN_tools/core.py

@@ -0,0 +1,286 @@
+"""
+MBN_tools package
+
+Core tools for working with MBN Explorer IO files and simulations.
+"""
+
+import numpy as np
+import warnings
+from typing import Union, Optional, List, Dict, Tuple
+
+
+def create_structured_array(atoms: List[str], frames: Union[np.ndarray, List[np.ndarray]]) -> np.ndarray:
+    """
+    Create a single 3D structured numpy array from a list of atom types and a nested list/array of coordinates for multiple frames.
+    
+    Parameters:
+        atoms (list of str): A list of atom type labels.
+        frames (numpy array or list): A list or array of 3D coordinates for multiple frames 
+                                      (shape: MxNx3, where M is the number of frames, and N is the number of atoms).
+        
+    Returns:
+        numpy.ndarray: A 3D structured array with 'atoms' and 'coordinates' fields, one for each frame.
+    """
+    
+    frames = np.array(frames)
+    
+    dtype = [('atoms', 'U10'), ('coordinates', 'f8', 3)]
+    
+    structured_array = np.array(
+        [[(atom, coord) for atom, coord in zip(atoms, frame)] for frame in frames],
+        dtype=dtype
+    )
+    
+    return structured_array
+
+
+def run_task(task_file: str, MBN_path: str, show_output: bool = False) -> Tuple[str, str]:
+    """
+    Run an MBN Explorer simulation using a specified Task file and return the standard output and error.
+
+    Parameters:
+        task_file (str): Path to the Task file.
+        MBN_path (str): Path to the MBN Explorer executable.
+        show_output (bool, optional): If True, prints the simulation output to the screen. Default is False.
+
+    Returns:
+        tuple: (stdout, stderr) where stdout and stderr are strings containing the standard output and error of the simulation.
+    """
+        
+    import subprocess
+    result = subprocess.run(MBN_path + ' -t ' + task_file, capture_output=True, text=True, creationflags=0x08000000)
+
+    if show_output:
+        print('Output:')
+        if len(result.stdout) > 0:
+            print(result.stdout)
+        else:
+            print(result.stderr)
+
+    return result.stdout, result.stderr
+
+
+def read_task(task_file: str, flatten: bool = False) -> Dict[str, Dict[str, str]]:
+    """
+    Read a Task file and split it into a dictionary of options and their parameters.
+
+    Parameters:
+        task_file (str): Path to the Task file.
+        flatten (bool, optional): If True, flattens the nested dictionary into a single dictionary. Default is False.
+
+    Returns:
+        dict: A dictionary of Task file options. If flatten=True, a flattened dictionary ignoring Task file sections.
+    """
+    
+    file_options = {}
+    with open(task_file) as f:
+        data = f.read().split('\n')
+    
+    section_options = {}
+    for line in data:
+        try:
+            if line[0] ==';' and len(line)>1:
+                if len(section_options)>0:
+                    file_options[section] = section_options
+                    section_options = {}
+                section = line.replace(';','').strip()
+            if '=' in line:
+                line=line.split(' = ')
+                section_options[line[0].strip()] = str(line[1].strip())
+        except IndexError:
+            pass
+    file_options[section] = section_options
+    
+    if flatten:
+        file_options_flat = {}
+        for key in file_options.keys():
+            file_options_flat.update(file_options[key])
+        return file_options_flat
+    else:
+        return file_options
+    
+
+def write_task(task_file: str, file_options: Dict[str, Dict[str, str]]) -> None:
+    """
+    Write a dictionary of Task file options to a Task file.
+
+    Parameters:
+        task_file (str): Path to the Task file.
+        file_options (dict): A dictionary of Task file options, where the keys are section headers and the values are dictionaries of parameters.
+    
+    Returns:
+        None: Writes the Task file.
+    """
+    
+    with open(task_file, 'w') as f:
+        f.write(';\n')
+        for key in file_options:
+            f.write('\n; '+key+'\n')
+            for sub_key in file_options[key]:
+                if sub_key == 'Random':
+                    f.write('\n'+'{:<31}'.format(sub_key)+'= '+file_options[key][sub_key]+'\n')
+                else:
+                    f.write('{:<31}'.format(sub_key)+'= '+file_options[key][sub_key]+'\n')
+
+
+def read_xyz(xyz_file: str) -> np.ndarray:
+    """
+    Read an XYZ file and return its contents as a structured array.
+
+    Parameters:
+        xyz_file (str): Path to the XYZ file.
+
+    Returns:
+        numpy.ndarray: A structured array with fields 'atoms' and 'coordinates'.
+    """
+    
+    with open(xyz_file, 'r') as f:
+        data = [i.split() for i in f.read().split('\n')[2:-1]]
+        atoms = [i[0] for i in data]
+        coordinates = [[[float(i[1]), float(i[2]), float(i[3])] for i in data]]
+
+    xyz_data = create_structured_array(atoms, coordinates)
+
+    return xyz_data
+
+
+def write_xyz(coords: np.ndarray, xyz_file: str, frame: int = 0) -> None:
+    """
+    Write coordinates to an XYZ file from a structured array.
+
+    Parameters:
+        coords (numpy.ndarray): A structured array of coordinates.
+        xyz_file (str): Path to the XYZ file.
+        frame (int, optional): The simulation frame to use if multiple are specified. Defaults to the first frame.
+    
+    Returns:
+        None: Writes the XYZ file.
+    """
+    
+    with open(xyz_file, 'w') as f:
+        f.write(str(len(coords[frame]))+'\n')
+        f.write('Type name\t\t\tPosition X\t\t\tPosition Y\t\t\tPosition Z\n')
+        for line in coords[frame]:
+            f.write(line['atoms']+'\t\t\t\t'+'\t\t'.join(['{:.8e}'.format(float(x)) for x in line['coordinates']])+'\n')
+
+
+def read_trajectory(dcd_file: str, xyz_file: str, frame: Optional[int] = None) -> np.ndarray:
+    """
+    Read coordinates from a DCD trajectory file and match them with atom labels from an XYZ file.
+
+    Parameters:
+        dcd_file (str): Path to the DCD file.
+        xyz_file (str): Path to the XYZ file containing atom labels.
+        frame (int, optional): The specific frame to return. If None, returns all frames.
+
+    Returns:
+        numpy.ndarray: A structured array of coordinates for the specified frame with fields 'atoms' and 'coordinates'.
+    """
+    
+    import mdtraj.formats as md
+    
+    with md.DCDTrajectoryFile(dcd_file) as f:
+        xyz, cell_lengths, cell_angles = f.read()
+        #coords = (xyz)
+
+    atoms = read_xyz(xyz_file)[0]['atoms']
+
+    coords = create_structured_array(atoms, (xyz))
+
+    if frame:
+        return coords[frame]
+    else:
+        return coords
+        
+        
+def xyz_to_pdb(xyz_file: str, pdb_file: str) -> None:
+    """
+    Update coordinates in a PDB file using new coordinates from an XYZ file.
+
+    Parameters:
+        xyz_file (str): Path to the XYZ file containing new coordinates.
+        pdb_file (str): Path to the PDB file with old coordinates.
+
+    Returns:
+        None: Writes a new PDB file with updated coordinates prefixed by 'new_'.
+    """
+    
+    with open(xyz_file) as xyz:
+        lines = xyz.readlines()
+        xyz_list = [line.strip().split() for line in lines[2:]]
+
+    with open(pdb_file) as pdb:
+        lines = pdb.readlines()
+        head = []
+        atoms = []
+        foot = []
+        atoms_done = False
+        for line in lines:
+            if line.startswith('ATOM'):
+                atoms.append(line.strip().split())
+            elif line.startswith('END'):
+                atoms_done = True
+                foot.append(line)
+            elif atoms_done:
+                foot.append(line)
+            else:
+                head.append(line)
+
+    with open('new_' + pdb_file, 'w') as new_pdb:
+        for line in head:
+            new_pdb.write(line)
+        for idx, atom in enumerate(atoms):
+            updated_atom = "{ATOM}{atom_num} {atom_name}{alt_loc_ind}{res_name} {chain_id}{res_seq_num}{res_code}   {x_coord}{y_coord}{z_coord}{occ}{temp}      {seg_id}{element}{charge}\n".format( #The values on the lines below can be edited to comply with other PDB types
+                ATOM=atom[0].ljust(6),
+                atom_num=atom[1].rjust(5),
+                atom_name=atom[2].ljust(4),
+                alt_loc_ind=' ',
+                res_name=atom[3].rjust(3),
+                chain_id=' ',
+                res_seq_num=atom[4].rjust(4),
+                res_code=' ',
+                x_coord=str('%3.3f' % (float(xyz_list[idx][1]))).rjust(8),
+                y_coord=str('%3.3f' % (float(xyz_list[idx][2]))).rjust(8),
+                z_coord=str('%3.3f' % (float(xyz_list[idx][3]))).rjust(8),
+                occ=str('%1.2f' % (float(atom[8]))).rjust(6),
+                temp=str('%1.2f' % (float(atom[9]))).rjust(6),
+                seg_id=atom[10].ljust(4),
+                element=atom[11].rjust(2),
+                charge='  '
+            )
+
+            new_pdb.write(updated_atom)
+        for line in foot:
+            new_pdb.write(line)
+#TODO: Switch to new strucutred array method
+
+
+def xyz_to_input(xyz: Union[str, np.ndarray], input_file: str, charge: Optional[str] = None, fixed: Optional[Union[int, List[int]]] = None, frame: int = 0) -> None:
+    """
+    Convert an XYZ file to an MBN Explorer input file.
+
+    Parameters:
+        xyz (str or numpy.ndarray): Path to an XYZ file or a structured array of coordinates.
+        input_file (str): Path to the output MBN Explorer input file.
+        charge (str, optional): Charge of the atoms, if specified. Default is None.
+        fixed (int or list of int, optional): Index or indices of fixed blocks. Default is None.
+        frame (int, optional): The simulation frame to use if multiple are specified. Defaults to the first frame.
+
+    Returns:
+        None: Writes the input file for MBN Explorer.
+    """
+    
+    if type(xyz) == str:
+        coords = read_xyz(xyz)[0]
+    elif type(xyz) == np.ndarray:
+        coords = xyz[0]
+    
+    with open(input_file, 'w') as f:
+        for i, line in enumerate(coords):
+            if i==fixed:
+                f.write('<*\n')
+            f.write(line['atoms']+(':'+charge if charge else '')+'\t\t\t'+'\t\t'.join(['{:.8e}'.format(float(x)) for x in line['coordinates']])+'\n')
+        if fixed:
+            f.write('>')
+#TODO: Add dictionary of charges
+#TODO: Change fixed to be lists. First item is start index, second is end index. Also list of lists. Single length list corresponds to fixed block after given index to end of file