MBN-tools 1.0.0__py3-none-any.whl

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/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/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

MBN_tools/crystallography.py

@@ -0,0 +1,163 @@
+"""
+MBN_tools.crystallography
+
+A collection of crystallography-related utility functions for analysing
+atomic structures produced by MBN Explorer simulations.
+
+This module provides tools for:
+- Grouping atoms relative to crystalline planes based on Miller indices.
+- Translating atomic coordinates onto specified planes.
+- Removing atoms within an exclusion region at the boundaries of a simulation box.
+
+Dependencies:
+- numpy
+
+Example:
+    import MBN_tools as MBN
+    from MBN_tools import crystallography
+
+    # Read coordinates from .xyz file
+    xyz_data = MBN.read_xyz('xyz_file.xyz')
+    atom_coords = xyz_data['coordinates']
+
+    # Remove all atoms within a certain distance from simulation box edge
+    filtered_atoms, removed_atoms = crystallography.remove_atoms_exclusion_region(atom_coords, box_size=30.0, shell_size=5.0)
+
+    # Finds centre coordinate of all 110 crystalline planes
+    planes = crystallography.group_atoms_by_plane(filtered_atoms, (1, 1, 0), tolerance=0.5)
+
+    # Translate the cebtre point of planes to a the 001 normal
+    for atoms, centre in planes:
+        coords.append(centre)
+
+    translated_coords = crystallography.translate_to_plane(coords, np.array([0, 0, 1]))
+"""
+
+import numpy as np
+from typing import List, Tuple
+
+def group_atoms_by_plane(structured_array: np.ndarray,
+                         hkl: Tuple[int, int, int],
+                         tolerance: float = 0.6) -> List[Tuple[np.ndarray, np.ndarray]]:
+
+    """
+    Group atoms by their position relative to a particular crystalline plane and calculate the centre of each plane,
+    using a tolerance-based approach to more accurately group atoms to planes.
+    
+    Parameters:
+        structured_array (numpy.ndarray): The structured array containing atom types and coordinates.
+        hkl (tuple): The Miller indices (h, k, l) defining the crystalline plane.
+        tolerance (float): Tolerance value for grouping atoms to planes (in the same units as lattice constant and coordinates).
+        
+    Returns:
+        list: A list of tuples where each tuple contains an array of atoms on that plane and their centre coordinates.
+    """
+    
+    # Unpack the Miller indices
+    h, k, l = hkl
+    
+    # Define the plane normal
+    plane_normal = np.array([h, k, l])
+    
+    # Normalize the plane normal
+    norm_plane_normal = np.linalg.norm(plane_normal)
+    plane_normal = plane_normal / norm_plane_normal
+    
+    # Project the atomic coordinates onto the plane normal to find their positions along this direction
+    projected_positions = np.dot(structured_array['coordinates'], plane_normal)
+    
+    # Initialize a list to store groups of atoms for each plane
+    planes = []
+    
+    # Sort the projected positions to process them in order
+    sorted_indices = np.argsort(projected_positions)
+    sorted_positions = projected_positions[sorted_indices]
+    sorted_atoms = structured_array[sorted_indices]
+    
+    # Initialize the first plane
+    current_plane_d = sorted_positions[0]
+    current_plane_atoms = []
+    
+    # Group atoms into planes based on their position
+    for pos, atom in zip(sorted_positions, sorted_atoms):
+        # If the atom is within the tolerance of the current plane, add it to the plane
+        if abs(pos - current_plane_d) <= tolerance:
+            current_plane_atoms.append(atom)
+        else:
+            # Finalize the current plane and calculate its centre
+            if current_plane_atoms:
+                plane_atoms_array = np.array(current_plane_atoms, dtype=structured_array.dtype)
+                centre_coordinates = np.nanmean(plane_atoms_array['coordinates'], axis=0)
+                planes.append((plane_atoms_array, centre_coordinates))
+            
+            # Start a new plane
+            current_plane_d = pos
+            current_plane_atoms = [atom]
+    
+    # Finalize the last plane
+    if current_plane_atoms:
+        plane_atoms_array = np.array(current_plane_atoms, dtype=structured_array.dtype)
+        centre_coordinates = np.nanmean(plane_atoms_array['coordinates'], axis=0)
+        planes.append((plane_atoms_array, centre_coordinates))
+    
+    return planes
+
+
+def translate_to_plane(coordinates: np.ndarray,
+                       normal_vector: np.ndarray,
+                       d: float = 0) -> np.ndarray:
+
+    """
+    Translate coordinates so that they lie on the specified plane.
+
+    Parameters:
+    - coordinates (numpy.ndarray): The atomic coordinates array, shape (N, 3).
+    - normal_vector (numpy.ndarray): The normal vector of the plane.
+    - d (float): The constant d in the plane equation ax + by + cz + d = 0. Default is 0.
+
+    Returns:
+    - translated_coordinates (numpy.ndarray): Coordinates translated to lie on the plane.
+    """
+    # Normalize the normal vector
+    normal_vector = normal_vector / np.linalg.norm(normal_vector)
+    
+    # Calculate the distance from each coordinate to the plane
+    distances = np.dot(coordinates, normal_vector) + d
+    
+    # Translate each coordinate by the distance along the normal vector
+    translated_coordinates = coordinates - np.outer(distances, normal_vector)
+    
+    return translated_coordinates
+
+
+def remove_atoms_exclusion_region(structured_array: np.ndarray,
+                                  box_size: float,
+                                  shell_size: float) -> Tuple[np.ndarray, np.ndarray]:
+
+    """
+    Remove atoms that are within a specified boundary distance from the edges of a simulation box.
+
+    Parameters:
+        structured_array (numpy structured array): A structured array containing atom data, including coordinates.
+        box_size (float): The size of the simulation box (assumed cubic).
+        shell_size (float): The distance from the edge of the box within which atoms should be removed.
+    
+    Returns:
+        numpy structured array: A filtered structured array with atoms near the edges removed.
+    """
+    
+        # Calculate the center of the crystal (assuming cubic box)
+    centre = box_size / 2.0
+    
+    # Get the coordinates of all atoms
+    coordinates = structured_array['coordinates']
+
+    condition_remove = np.where(np.any(np.abs(coordinates)>centre - shell_size, axis=1))[0]
+    
+    # Atoms outside the boundary
+    removed_atoms = structured_array[condition_remove]
+    
+    # Atoms inside the boundary
+    filtered_atoms = structured_array[~np.any(np.abs(coordinates)>centre - shell_size, axis=1)]
+    
+    return filtered_atoms, removed_atoms

MBN_tools/visualise.py

@@ -0,0 +1,175 @@
+"""
+MBN_tools.visualise
+
+A collection of 3D visualisation utilities for MBN Explorer simulations using VisPy.
+
+This submodule provides tools to:
+- Draw transparent simulation boxes with wireframe edges.
+- Render arbitrary 3D planes with configurable orientation and border.
+- Plot atom positions as markers with customisable appearance.
+
+Dependencies:
+- numpy
+- vispy
+
+Example:
+    import MBN_tools as MBN
+    from MBN_tools import visualise
+    import vispy.scene
+
+    # Create a canvas and a 3D view
+    canvas = vispy.scene.SceneCanvas(keys='interactive', show=True, bgcolor='white')
+    view = canvas.central_widget.add_view()
+
+    # Read coordinates from .xyz file
+    xyz_data = MBN.read_xyz('xyz_file.xyz')
+    atom_coords = xyz_data['coordinates']
+
+    # Draw a simulation box, a plane, and some atoms
+    visualisation.draw_simulation_box(30, 30, 30, parent=view.scene)
+    visualisation.draw_plane(centre=(0,0,0), size_x=10, size_y=10, normal=(0,0,1), parent=view.scene)
+    visualisation.draw_atoms(atom_coords, face_color=(1,0,0,1), symbol='o', size=12, parent=view.scene)
+"""
+
+import numpy as np
+import vispy.scene
+from vispy.scene import visuals
+from typing import Tuple, Optional, Union, Any
+
+ColorType = Union[Tuple[float, float, float, float], str]
+
+def draw_simulation_box(size_x: float, size_y: float, size_z: float,
+                        edge_color: ColorType = (0, 0, 0, 1),
+                        edge_width: int = 2,
+                        parent: Optional[Any] = None) -> vispy.scene.visuals.Line:
+    """
+    Draw a transparent 3D box (rectangular cuboid) with visible wireframe edges.
+
+    Parameters:
+    - size_x (float): Size of the box in the x-direction.
+    - size_y (float): Size of the box in the y-direction.
+    - size_z (float): Size of the box in the z-direction.
+    - edge_color (tuple): RGBA color of the box edges. Default is black.
+    - edge_width (int): Width of the box edges. Default is 2.
+    - parent (Node, optional): Parent VisPy node to which this box will be attached.
+
+    Returns:
+    - vispy.scene.visuals.Line: The wireframe visual representing the box.
+    """
+    # Define the 8 vertices of the box
+    vertices = np.array([
+        [-size_x / 2, -size_y / 2, -size_z / 2],
+        [ size_x / 2, -size_y / 2, -size_z / 2],
+        [ size_x / 2,  size_y / 2, -size_z / 2],
+        [-size_x / 2,  size_y / 2, -size_z / 2],
+        [-size_x / 2, -size_y / 2,  size_z / 2],
+        [ size_x / 2, -size_y / 2,  size_z / 2],
+        [ size_x / 2,  size_y / 2,  size_z / 2],
+        [-size_x / 2,  size_y / 2,  size_z / 2],
+    ])
+
+    # Define the 12 edges of the box
+    edges = np.array([
+        [0, 1], [1, 2], [2, 3], [3, 0], # bottom face
+        [4, 5], [5, 6], [6, 7], [7, 4], # top face
+        [0, 4], [1, 5], [2, 6], [3, 7]  # vertical edges
+    ])
+
+    # Create the box edges (wireframe only)
+    box_edges = vispy.scene.visuals.Line(pos=vertices, connect=edges, color=edge_color, 
+                                   parent=parent, width=edge_width)
+
+    # Set the box to be transparent by not adding a face visual
+    # If you were using a filled mesh, you would set `face_color` to be transparent
+
+    return box_edges
+
+
+def draw_plane(centre: Tuple[float, float, float],
+               size_x: float, size_y: float,
+               normal: Tuple[float, float, float],
+               color: ColorType = (1, 1, 1, 1),
+               edge_color: ColorType = (0, 0, 0, 1),
+               parent: Optional[Any] = None) -> Tuple[vispy.scene.visuals.Mesh, vispy.scene.visuals.Line]:
+
+    """
+    Draw a plane in 3D space with adjustable size in each direction, a specified normal vector, and a border.
+
+    Parameters:
+    - centre: A tuple (x, y, z) specifying the centre of the plane.
+    - size_x: The size of the plane along the first basis vector direction.
+    - size_y: The size of the plane along the second basis vector direction.
+    - normal: A 3-element tuple specifying the normal vector of the plane.
+    - color: The color of the plane with RGBA format (default is white).
+    - edge_color: The color of the edges with RGBA format (default is black).
+    - parent: The parent node to which this plane will be added (default is None).
+
+    Returns:
+    - A tuple containing the Mesh visual of the plane and the Line visual of the border.
+    """
+
+    # Normalize the normal vector
+    normal = np.array(normal) / np.linalg.norm(normal)
+
+    # Create an arbitrary vector that is not parallel to the normal
+    if np.allclose(normal, [0, 0, 1]):
+        basis1 = np.array([1, 0, 0])
+    else:
+        basis1 = np.cross(normal, [0, 0, 1])
+        basis1 /= np.linalg.norm(basis1)  # Normalize basis1
+
+    # Create the second basis vector
+    basis2 = np.cross(normal, basis1)
+
+    # Create the vertices of the plane using the local basis vectors
+    half_size_x = size_x / 2
+    half_size_y = size_y / 2
+    vertices = np.array([
+        -half_size_x * basis1 - half_size_y * basis2,
+         half_size_x * basis1 - half_size_y * basis2,
+         half_size_x * basis1 + half_size_y * basis2,
+        -half_size_x * basis1 + half_size_y * basis2,
+    ]) + np.array(centre)
+
+    # Define the indices that connect the vertices to form two triangles
+    indices = np.array([0, 1, 2, 0, 2, 3])
+
+    # Create the plane as a Mesh visual
+    plane = vispy.scene.visuals.Mesh(vertices=vertices, faces=indices.reshape((-1, 3)),
+                               color=color, parent=parent)
+
+    # Create the edges of the plane as a Line visual
+    edges = vispy.scene.visuals.Line(pos=np.append(vertices, [vertices[0]], axis=0),  # Close the loop
+                               color=edge_color, width=2, parent=parent, connect='strip')
+
+    return plane, edges
+
+
+def draw_atoms(atom_coordinates: np.ndarray,
+               face_color: ColorType = (1, 1, 1, 1),
+               edge_color: ColorType = (0, 0, 0, 1),
+               symbol: str = 'o',
+               edge_width: float = 1,
+               size: float = 10,
+               parent: Optional[Any] = None) -> vispy.scene.visuals.Markers:
+
+    """
+    Draw a collection of atoms as markers in 3D space.
+
+    Parameters:
+    - atom_coordinates (numpy.ndarray): Nx3 array of atomic coordinates.
+    - face_color (tuple): RGBA color of marker faces. Default is white.
+    - edge_color (tuple): RGBA color of marker edges. Default is black.
+    - symbol (str): Marker shape (e.g. 'o' for circle, 's' for square).
+    - edge_width (float): Width of marker edges.
+    - size (float): Size of the markers.
+    - parent (Node, optional): Parent VisPy node to attach the markers to.
+
+    Returns:
+    - vispy.scene.visuals.Markers: The visual representing the atoms.
+    """
+    atoms = visuals.Markers(parent=parent)
+    atoms.set_data(atom_coordinates, face_color=face_color, edge_color=edge_color,
+                   edge_width=edge_width, size=size, symbol=symbol)
+
+    return atoms

mbn_tools-1.0.0.dist-info/METADATA

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: MBN_tools
+Version: 1.0.0
+Summary: Useful tools for use with MBN Explorer simulations, files, and their analysis
+Author-email: Matthew Dickers <mattdickers@gmail.com>
+License: 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.
+        
+Project-URL: Homepage, https://github.com/mattdickers/MBN-tools
+Project-URL: Source, https://github.com/mattdickers/MBN-tools
+Keywords: MBN Explorer,MBN Studio,Molecular Dynamics,MD,Data Analysis
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE.txt
+Requires-Dist: numpy>=1.26
+Requires-Dist: scipy>=1.12
+Requires-Dist: mdtraj
+Requires-Dist: vispy
+Dynamic: license-file
+
+
+# MBN Tools
+
+**MBN Tools** provides a set of utilities for running, processing, and analysing simulations with [MBN Explorer](https://mbnresearch.com/get-mbn-explorer-software).
+
+## Features
+
+- **Run MBN Explorer simulations**  
+  Run MBN Explorer simulation tasks directly from Python.
+
+- **File handling utilities**  
+  Create, read, modify, and convert simulation input/output files including `.task`, `.xyz`, `.dcd`, and`.pdb`.
+
+- **Trajectory analysis**  
+  Analyze simulation outputs, including radial distribution functions (RDF), mean squared displacement (MSD), RMSD, and more.
+
+- **Crystallography utilities**  
+  Group atoms by crystallographic planes, translate coordinates to planes, and remove atoms near simulation boundaries.
+
+- **3D visualisation**  
+  Render atoms, planes, and simulation boxes in 3D using `VisPy` with customisable colours, sizes, and markers.
+
+## Installation
+
+```bash
+pip install MBN-tools
+```
+
+## Usage
+```python
+import MBN_tools as MBN
+from MBN_tools import analysis, crystallography, visualise
+
+# Run an MBN Explorer simulation
+stdout, stderr = MBN.run_task("example.task", "/path/to/MBN_Explorer")
+
+# Read an XYZ file
+xyz_data = MBN.read_xyz("simulation.xyz")
+
+# Compute RMSD
+rmsd_values = analysis.calculate_rmsd(xyz_data, box_size=[50, 50, 100])
+
+# Group atoms by a crystalline plane
+planes = crystallography.group_atoms_by_plane(xyz_data, hkl=(1,1,0), tolerance=0.5)
+
+# Visualize atoms in 3D
+canvas = visualise.create_canvas()
+visualise.draw_atoms(xyz_data['coordinates'], parent=canvas.central_widget.add_view())
+```
+
+## Dependencies
+
+- `numpy >= 1.26`
+- `scipy >= 1.12`
+- `mdtraj`
+- `vispy`

mbn_tools-1.0.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+MBN_tools/__init__.py,sha256=b6kr80R_sZ7qJf-s4Ygwb8s_yaAEn5jeEOUMAxupP-c,1173
+MBN_tools/analysis.py,sha256=K-USyY7H85CtnJwhP0gUiMKaxuE-oySixDg6RpUBoSA,7458
+MBN_tools/core.py,sha256=Ebr_u_iNV5CM4MvEchJeQcQRBP8O8tVcQNC4rN1LiJ0,10673
+MBN_tools/crystallography.py,sha256=xu58IEgoa8MmvANGFcjORG-YhmHL6VkneVbZRc9fiZM,6615
+MBN_tools/visualise.py,sha256=mNKy1xxLnwR46vDwzqZQs3QF0cmcipOaaNNVWGLt7-4,7073
+mbn_tools-1.0.0.dist-info/licenses/LICENSE.txt,sha256=rObxqiGzkOrl9qyG_7-Lpt1yWi5V0F7a8gj3foRt8Bw,1070
+mbn_tools-1.0.0.dist-info/METADATA,sha256=nffm8U6FufJj6psQrWrwYj3xDho052PkeBqHWe7C49g,3917
+mbn_tools-1.0.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
+mbn_tools-1.0.0.dist-info/top_level.txt,sha256=rD-wUhF3PVoN6Sie6ZUp0H-tzEuTwaG0ZzHgDdfjMk4,10
+mbn_tools-1.0.0.dist-info/RECORD,,

mbn_tools-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.10.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mbn_tools-1.0.0.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+MBN_tools