imperial-materials-simulation 0.0.1__tar.gz

imperial_materials_simulation-0.0.1/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: imperial_materials_simulation
+Version: 0.0.1
+Summary: Molecular simulation tool made for the undergraduate materials science and engineering theory and simulation module at Imperial College London
+Home-page: https://github.com/AyhamSaffar/imperial_materials_simulation
+Author: Ayham Al-Saffar
+Requires-Python: ~=3.10
+Description-Content-Type: text/markdown
+
+This is a test to make sure this comes up

imperial_materials_simulation-0.0.1/README.md

@@ -0,0 +1 @@
+This is a test to make sure this comes up

imperial_materials_simulation-0.0.1/imperial_materials_simulation/__init__.py

@@ -0,0 +1,29 @@
+# __init__.py
+import pandas as pd
+from imperial_materials_simulation.main import Simulation, load_simulation
+
+starting_microstructure = pd.DataFrame(
+    [[ 1.26130966, -3.6279824 ,  3.22874575],
+     [ 0.01109185, -3.81654351,  2.36666413],
+     [-1.35980652, -3.29266717,  1.93055455],
+     [-2.37977009, -2.15076958,  1.87652048],
+     [-2.57604888, -0.67746009,  2.24917055],
+     [-1.87620203,  0.5914393 ,  2.74767705],
+     [-0.5004315 ,  1.22611982,  2.97495106],
+     [ 1.00344892,  1.14070135,  2.69818462],
+     [ 2.12602653,  0.50009417,  1.87770294],
+     [ 2.5645804 , -0.39591704,  0.7168456 ],
+     [ 2.18172369, -1.32983529, -0.43350902],
+     [ 1.10831734, -1.9090663 , -1.35772197],
+     [-0.30107549, -1.83240466, -1.94918892],
+     [-1.58628718, -1.03144403, -2.17155873],
+     [-2.40576488,  0.23981749, -1.93470708],
+     [-2.43673373,  1.66539118, -1.37583959],
+     [-1.61465889,  2.84516096, -0.8471113 ],
+     [-0.1902823 ,  3.40079245, -0.74306813],
+     [ 1.24620565,  3.26671434, -1.25936233],
+     [ 2.09305162,  2.57081936, -2.32976298],
+     [ 2.17803079,  1.66144767, -3.55851113],
+     [ 1.45327508,  0.95559197, -4.70667552]],
+        columns=['x', 'y', 'z']
+)

imperial_materials_simulation-0.0.1/imperial_materials_simulation/display.py

@@ -0,0 +1,158 @@
+'''
+Methods for creating interactive visualisations of the simulated molecule and its measurements
+within Jupyter Notebook using ipywidgets. 
+'''
+import ipywidgets as ipy
+import py3Dmol
+import matplotlib.pyplot as plt
+import matplotlib
+import pandas as pd
+from IPython.display import display, clear_output
+
+class SimulationDashboard():
+    '''
+    Class for creating inline Jupter Notebook visualisations of how the measurements and microstructure of simulated
+    molecules vary live with time. This is built on top of the library's Simulation object.
+    '''
+
+    def __init__(self, sim) -> None:
+        '''Initiates internal methods, attributes, and dashboard widgets'''
+        #TODO replace matplotlib with plotly for speed
+        matplotlib.use('module://ipympl.backend_nbagg')
+        self.sim = sim
+
+        self.mol_viewer = py3Dmol.view(width=300, height=300)
+        with plt.ioff():
+            self.fig, self.left_ax = plt.subplots(figsize=(6, 3))
+            self.fig.tight_layout(pad=2)
+            self.right_ax = self.left_ax.twinx()
+            self.line = self.right_ax.axvline(x=0.5, color='black', linestyle='--')
+        self.fig.canvas.header_visible = False
+        self.fig.canvas.toolbar_visible = False
+        self.fig.canvas.footer_visible = False
+
+        self.observers_enabled = False
+        self.run_slider = ipy.IntSlider(value=0, min=0, max=0, description='Run', orientation='vertical')
+        self.table_widget = ipy.Output(layout=ipy.Layout(height='200px', overflow='auto'))
+        with self.table_widget:
+            display(self.sim.run_data)
+        top_box = ipy.HBox(children=[self.run_slider, self.table_widget])
+        self.step_slider = ipy.IntSlider(value=0, min=0, max=0, step=self.sim.microstructure_logging_interval,
+                                         description='Step', orientation='Horizontal', layout=ipy.Layout(width='900px'))
+        self.left_axis_selector = ipy.Dropdown(options=(), description='left (red)')
+        self.right_axis_selector = ipy.Dropdown(options=(), description='right (blue)')
+        selector_box = ipy.HBox(children=[self.left_axis_selector, self.right_axis_selector])
+        plot_box = ipy.Output()
+        with plot_box:
+            self.fig.show()
+        plot_box = ipy.VBox(children=[plot_box, selector_box])
+        self.molecule_box = ipy.Output()
+        self._redraw_molecule()
+        bottom_box = ipy.HBox(children=[plot_box, self.molecule_box], layout=ipy.Layout(align_items='center'))
+        self.display_widget = ipy.VBox(children=[top_box, self.step_slider, bottom_box])
+        self._enable_observers()
+    
+    def display(self, sim) -> None:
+        '''Creates an instance of the dashboard in the output of the notebook cell it is called in.'''
+        self.sim = sim
+        if self.sim.run_data['run'].max() > 0:
+            self.run_slider.max = self.sim.run_data['run'].max()
+            self.run_slider.min = 1
+        display(self.display_widget)
+    
+    def live_update(self, sim, step: int, run_type: str, n_steps: int, temperature: float):
+        '''Updates the dashboard live after new runs are started'''
+        self.sim = sim
+        if step > 0:
+            self.step_slider.value = step
+            self._redraw_molecule()
+            self._redraw_plot()
+            return
+        
+        #TODO freeze selectors during live update
+        current_run_data = {'run': self.sim.run, 'type': run_type, 'n_steps': n_steps, 'T': temperature}
+        with self.table_widget:
+            clear_output()
+            display(pd.concat([self.sim.run_data, pd.DataFrame(current_run_data, index=[0])]))
+        self._disable_observers()
+        self.run_slider.max += 1
+        self.step_slider.max = ((n_steps-1) // self.sim.microstructure_logging_interval) * self.sim.microstructure_logging_interval
+        self.run_slider.disabled = True
+        self.step_slider.disabled = True
+        self.run_slider.value = self.run_slider.max
+        self._reset_axis_selectors()
+
+    def reset(self, sim):
+        '''Resets the dashboard at the end of a live display run so it can continue to be used'''
+        self.sim = sim
+        self.run_slider.min = 1
+        self.run_slider.disabled = False
+        self.step_slider.disabled = False
+        with self.table_widget:
+            clear_output()
+            display(self.sim.run_data)
+        self._enable_observers()
+        self._redraw_plot()
+        self.step_slider.value = self.step_slider.max
+
+    def _step_slider_moved(self, _= None) -> None:  #placeholder arguement as widget observe calls method with redundant arguement 
+        self.step_slider.value = self.step_slider.value
+        self._redraw_molecule()
+        self.line.set_xdata([self.step_slider.value])
+        self.fig.canvas.draw()
+    
+    def _run_slider_moved(self, _= None) -> None:
+        self.step_slider.value = 0
+        self._reset_axis_selectors()
+        self.step_slider.max = self.sim.step_data[self.run_slider.value].shape[0]-self.sim.microstructure_logging_interval
+        self._redraw_plot()
+        self._redraw_molecule()
+
+    def _reset_axis_selectors(self):
+        self._disable_observers()
+        self.left_axis_selector.options = self.sim.step_data[self.run_slider.value].columns[1:]
+        self.right_axis_selector.options = self.sim.step_data[self.run_slider.value].columns[1:]
+        self.left_axis_selector.value, self.right_axis_selector.value = self.sim.step_data[self.run_slider.value].columns[-2:]
+        self._enable_observers()
+
+    def _disable_observers(self):
+        if self.observers_enabled == False:
+            return
+        self.observers_enabled = False
+        self.step_slider.unobserve(self._step_slider_moved, names='value')
+        self.run_slider.unobserve(self._run_slider_moved, names='value')
+        self.left_axis_selector.unobserve(self._redraw_plot, names='value')
+        self.right_axis_selector.unobserve(self._redraw_plot, names='value')
+
+    def _enable_observers(self):
+        if self.observers_enabled:
+            return
+        self.observers_enabled = True
+        self.step_slider.observe(self._step_slider_moved, names='value')
+        self.run_slider.observe(self._run_slider_moved, names='value')
+        self.left_axis_selector.observe(self._redraw_plot, names='value')
+        self.right_axis_selector.observe(self._redraw_plot, names='value')
+
+    def _redraw_molecule(self, _=None) -> None: 
+        structure = self.sim.microstructures[self.run_slider.value][self.step_slider.value].copy()
+        structure.insert(loc=0, column='element', value='C')
+        molecule_xyz = f'{len(structure)}\n some comment\n {structure.to_string(header=False, index=False)}'
+        self.mol_viewer.clear()
+        self.mol_viewer.addModel(molecule_xyz, 'xyz')
+        self.mol_viewer.setStyle({'stick': {'colorscheme': 'default'}, 'sphere': {'scale': 0.3, 'colorscheme': 'cyanCarbon'}})
+        self.mol_viewer.zoomTo()
+        with self.molecule_box:
+            self.mol_viewer.update()
+        
+    def _redraw_plot(self, _=None) -> None: 
+        left_data = self.sim.step_data[self.run_slider.value][self.left_axis_selector.value]
+        right_data = self.sim.step_data[self.run_slider.value][self.right_axis_selector.value]
+        self.left_ax.clear()
+        self.right_ax.clear()
+        self.left_ax.set_yscale('log' if left_data.max() > left_data.min()*100 and left_data.min() > 0 else 'linear')
+        self.right_ax.set_yscale('log' if right_data.max() > right_data.min()*100 and right_data.min() > 0 else 'linear')
+        self.right_ax.ticklabel_format(axis='x', style='sci', scilimits=(0,4))
+        self.left_ax.plot(left_data, color='red')
+        self.right_ax.plot(right_data, color='blue')
+        self.line = self.right_ax.axvline(x=self.step_slider.value, color='black', linestyle='--')
+        self.fig.canvas.draw()

imperial_materials_simulation-0.0.1/imperial_materials_simulation/main.py

@@ -0,0 +1,398 @@
+from . import physics, display
+import numpy as np
+import numpy.random as rand
+import pandas as pd
+import pickle
+import warnings
+
+
+class Simulation():
+   '''
+   A script for atomistic simulations of toy polymers. Each polymer is a linear string of beads
+   (CH2 units) with no side chains. Bonds are springs and nonbonded atoms interact via a 12-6
+   Lennard-Jones potential.
+   
+   Four methods of atomistic simulation are implemented: 
+
+      (1) Steepest descent structural relaxation / energy minimization.
+
+      (2) Constant temperature ('NVT') dynamics with a Langevin thermostat. 
+
+      (3) Hamiltonian (aka `constant energy' or `NVE') molecular dynamics.
+
+      (4) Metropolis Monte Carlo ('MMC') stochastic model.
+
+   Paul Tangney, Ayham Al-Saffar 2024
+   '''
+
+   def __init__(self, n_atoms: int, starting_temperature: float, microstructure: pd.DataFrame = None,
+                microstructure_logging_interval: int = 100) -> None:
+      '''
+      Initializes internal microstate, physics, and display variables.
+      Units are in electron volts, femto-seconds, Angstroms, and Kelvin.
+
+      Parameters
+      ----------
+      n_atoms : int
+         Number of atoms in the simluated carbon chain.
+
+      starting_temperature : int
+         Temperature used when initiating atom velocities.
+
+      microstructure : pd.DataFrame
+         Dataframe specifying the intitial positions of each atom. Dataframe must have n_atoms rows
+         and the columns 'x', 'y', 'z'. If not given, a straight linear chain is created.
+
+      microstructure_logging_interval : int
+         How many steps are run between each time the microstrucutre is saved. This can be reduced
+         to as low as 10 without significantly impacting run speed, however this significantly
+         increases the size of the saved simulation file. 
+      '''
+      self.n_atoms = n_atoms
+      self.microstructure_logging_interval = microstructure_logging_interval
+      self.is_being_displayed = False
+      self.time_step = 0.8
+      self.mass = 1451.0 # 14 AMU (CH2 Mr) in eV fs^2/Å^2
+
+      #force parameters taken from https://doi.org/10.1063/1.476826 
+      self.sigma = 4.5 #equilibrium Lennard Jones atomic seperation
+      self.epsilon = 0.00485678 #Lennard Jones coefficient
+      self.bond_length = 1.53 #equilibrium neighbour bond length
+      self.spring_constant = 15.18
+
+      #increases initial Boltzmann distribution velocities when generating a new microstate as some
+      #of this energy is converted to potential energy. Its value should be 2.0 for a harmonic potential.
+      T_factor = 1.5 if microstructure is None else 1.0 #! Will discuss what this value should be on Friday
+      self.kB = 8.617333262e-05
+      self.target_kT = starting_temperature * self.kB
+      self.velocity_sigma = np.sqrt(self.target_kT/self.mass) #variance of Boltzmann distrubution velocities
+      self.velocities = rand.normal(loc=0.0, scale=np.sqrt(T_factor)*self.velocity_sigma, size=(self.n_atoms, 3))
+
+      self.forces = np.zeros(shape=(self.n_atoms, 3))
+      if microstructure is None:
+         self.positions = np.zeros(shape=(self.n_atoms, 3))
+         self.positions[:, 1] = np.linspace(start=0.0, stop=(self.n_atoms-1)*self.bond_length, num=self.n_atoms)
+      else:
+         assert microstructure.shape[0] == self.n_atoms
+         assert all([col in microstructure.columns for col in ['x', 'y', 'z']])
+         self.positions = microstructure[['x', 'y', 'z']].values
+      
+      self.positions -= np.mean(self.positions, axis=0, keepdims=True) #centre molecule
+      self.velocities -= np.mean(self.velocities, axis=0, keepdims=True) #remove overall molecule movement
+
+      #list with a dict {step: microstructure} for each run
+      self.microstructures = [{0: pd.DataFrame(self.positions, columns=['x', 'y', 'z']).copy()}]
+      self.run = 0
+      data_structure = {'run': int, 'type': str, 'n_steps': int, 'T': float, 'KE': float, 'PE_bonding': float,
+                        'PE_non_bonding': float, 'PE_total': float, 'F_rms': float, 'L_end_to_end': float}
+      self.run_data = pd.DataFrame({name: pd.Series(dtype=dtype) for name, dtype in data_structure.items()})
+      self._log_run_data(run_type='init', n_steps=0, temperature=starting_temperature)
+      self.step_data = {} #{run: dataframe}
+
+
+   def relax_run(self, n_steps: int, step_size: float = 0.01) -> None:
+      '''
+      Structural relaxation through steepest descent energy minimisation. This is a non-physical simulation
+      where the molecule is modelled as not experiencing any thermal forces. Each atom moves in the direction
+      that minimizes is potential energy the most, which is the net (bonding + non-bonding) force vector. 
+
+      Parameters
+      ----------
+      n_steps : int
+         Number of steps of steepest descent energy minimisation.
+
+      step_size: float
+         How far each atom should move with each step. The total movement vector is the relax_step_size * force
+         vector. 0.01 is a good starting point, but could be ~10x higher for the first few steps and ~10x smaller
+         for the last few steps.
+
+      '''
+      self.run += 1
+      self.microstructures.append({0: pd.DataFrame(self.positions, columns=['x', 'y', 'z'])})
+      step_data = []
+   
+      for step in range(n_steps):
+         F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+         F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+         self.positions += (F_nb + F_b) * step_size
+         step_data.append({
+            'step': step,
+            'PE_bonding': PE_b,
+            'PE_non_bonding': PE_nb,
+            'PE_total': PE_b + PE_nb,
+            'F_rms': np.mean((F_b + F_nb)**2) ** 0.5,
+            'L_end_to_end': np.sum((self.positions[0] - self.positions[-1]) ** 2) ** 0.5,
+         })
+         self._logging_step(step, step_data, run_type='relax', n_steps=n_steps, temperature=0.0)
+
+      self.step_data[self.run] = pd.DataFrame(step_data)
+      self._log_run_data(run_type='relax', n_steps=n_steps, temperature=0.0)
+      self.dashboard.reset(self) if self.is_being_displayed else print(f'{n_steps:,} step relax run completed')
+
+   def NVT_run(self, n_steps: int, temperature: float, gamma: float = 0.005, integrator: str = 'OVRVO'):
+      '''
+      Constant number of atoms, volume, and temperature (NVT) simulation with a Langevin thermostat. Simple
+      model that approximates the physical influence of a solute bath at a given temperature. It adds a drag
+      and random force onto the energy minimization force. https://doi.org/10.1021/jp411770f details different
+      techniques for integrating these forces over time.
+
+      Parameters
+      ----------
+      n_steps : int
+         Number of NVT steps to perform.
+
+      temperature: float
+         Temperature of simulation. A higher temperature leads to higher solute forces and so velocities. Note
+         the actual temperature of the simulation at each step (dictated by atom velocities) may vary slightly.
+         
+      gamma: float
+         Solvent interaction strength. Higher values lead to higher solute drag and random solute forces. 0 is
+         no solvent, 0.001 is weak interaction, 0.005 is medium interaction, and 0.1 is strong interaction
+
+      integrator: str
+         How forces are intergrated over time. Either 'OVRVO' or 'VRORV'. See paper for more details. 
+         #TODO make all available
+      '''
+      assert integrator in ('OVRVO', 'VRORV'), f'{integrator} integrator not supported'
+      self.run += 1
+      self.microstructures.append({0: pd.DataFrame(self.positions, columns=['x', 'y', 'z'])})
+      step_data = []
+   
+      self.target_kT = temperature * self.kB
+      self.velocity_sigma = np.sqrt(self.target_kT/self.mass) #variance of Boltzmann distrubution velocities
+
+      F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+      F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+      a = np.exp(-gamma / (self.time_step*2)) if integrator == 'OVRVO' else np.exp(-gamma/self.time_step)
+      b = np.sqrt(1 - a**2)
+      for step in range(n_steps):
+         if integrator == 'OVRVO':
+            self.velocities = self.velocities*a + rand.standard_normal((self.n_atoms, 3))*self.velocity_sigma*b
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+            self.positions += self.velocities*self.time_step
+            F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+            F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+            self.velocities = self.velocities*a + rand.standard_normal((self.n_atoms, 3))*self.velocity_sigma*b
+         elif integrator == 'VRORV':
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+            self.positions += self.velocities*self.time_step / 2
+            self.velocities = self.velocities*a + rand.standard_normal((self.n_atoms, 3))*self.velocity_sigma*b
+            self.positions += self.velocities*self.time_step / 2
+            F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+            F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+
+         ##TODO make sure it is okay that velocities are not re-normalised at this point
+         KE_total = physics.get_kintetic_energy(self.velocities, self.mass)
+         T_actual = physics.get_temperature(KE_total, self.n_atoms)
+         step_data.append({
+            'step': step,
+            'T_actual': T_actual,
+            'PE_total': PE_b + PE_nb,
+            'KE_total': KE_total,
+            'F_rms': np.mean((F_b + F_nb)**2) ** 0.5,
+            'L_end_to_end': np.sum((self.positions[0] - self.positions[-1]) ** 2) ** 0.5,
+         })
+         self._logging_step(step, step_data, run_type='NVT', n_steps=n_steps, temperature=temperature)
+      
+      self.step_data[self.run] = pd.DataFrame(step_data)
+      self._log_run_data(run_type='NVT', n_steps=n_steps, temperature=temperature)
+      self.dashboard.reset(self) if self.is_being_displayed else print(f'{n_steps:,} step NVT run completed')
+
+   def NVE_run(self, n_steps: int, temperature: float = None, integrator: str = 'step'):
+      '''
+      Constant number of atoms, volume, and energy (NVE) simulation. Used for modelling molecules in the
+      gas phase or finding an acceptable simulation timestep. Larger timesteps speed up the simulation
+      but will eventually break conservation of energy if too large. https://doi.org/10.1021/jp411770f
+      details different techniques for integrating the simulation forces over time.
+
+      Parameters
+      ----------
+      n_steps : int
+         Number of NVE steps to perform.
+
+      temperature: float
+         If given, resets the atom velocities to follow a boltzmann distribtuion at the
+         new tempearture. Should be given if this run is not preceded by an NVT run at
+         the desired temperature.
+
+      integrator : str
+         How forces are intergrated over time. Either 'continuous' or 'step'.
+         #TODO make all available
+      '''
+      assert integrator in ['continuous', 'step'], f'integrator {integrator} not supported'
+      self.run += 1
+      self.microstructures.append({0: pd.DataFrame(self.positions, columns=['x', 'y', 'z'])})
+      step_data = []
+
+      if temperature is not None:
+         self.target_kT = temperature * self.kB
+         self.velocity_sigma = np.sqrt(self.target_kT/self.mass) #variance of Boltzmann distrubution velocities
+         self.velocities = rand.normal(loc=0.0, scale=self.velocity_sigma, size=(self.n_atoms, 3))
+      else:
+         temperature = self.run_data.loc[self.run_data['run'] == (self.run-1), 'T'].values[0] #previous temperature
+      F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+      F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+   
+      for step in range(n_steps):
+         if integrator == 'continuous':
+            average_velocities = self.velocities + (F_b + F_nb)*self.time_step / (2*self.mass)
+            self.positions += average_velocities*self.time_step
+            F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+            F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+            self.velocities = average_velocities + (F_b + F_nb)*self.time_step / (2*self.mass)
+         if integrator == 'step':
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+            self.positions += self.velocities*self.time_step
+            F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+            F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+            self.velocities += (F_b + F_nb)*self.time_step / (2*self.mass)
+
+         KE_total = physics.get_kintetic_energy(self.velocities, self.mass)
+         step_data.append({
+            'step': step,
+            'PE_total': PE_b + PE_nb,
+            'KE_total': KE_total,
+            'F_rms': np.mean((F_b + F_nb)**2) ** 0.5,
+            'L_end_to_end': np.sum((self.positions[0] - self.positions[-1]) ** 2) ** 0.5,
+         })
+         self._logging_step(step, step_data, run_type='NVE', n_steps=n_steps, temperature=temperature)
+      
+      self.step_data[self.run] = pd.DataFrame(step_data)
+      self._log_run_data(run_type='NVE', n_steps=n_steps, temperature=temperature)
+      self.dashboard.reset(self) if self.is_being_displayed else print(f'{n_steps:,} step NVE run completed')
+
+   def MMC_run(self, n_steps: int, temperature: float, random_scale: float = 0.05):
+      '''
+      Metropolis Monte Carlo (MMC) Simulation. Randomly displaces atoms by a small amount and accepts the new
+      structure if it reduces total potential energy or has a chance of accepting the new structure ∝ exp(-ΔPE)
+      if it increases total potential energy. Un-physical but useful for sampling a variety of fairly low energy
+      microstructures for thermodynamic property prediction. 
+
+      Parameters
+      ----------
+      n_steps : int
+         Number of MMC steps to perform.
+
+      temperature: float
+         Temperature of simulation. A higher temperature means higher thermal energy, increasing tha chance
+         of an atom moving to a new random position.
+
+      random_scale: float 
+         Size limit of random displacement at each step. Will be +/- bond_length * random_scale / 2 in each direction.
+      '''
+      self.run += 1
+      self.microstructures.append({0: pd.DataFrame(self.positions, columns=['x', 'y', 'z'])})
+      step_data = []
+
+      self.target_kT = temperature * self.kB
+      self.velocity_sigma = np.sqrt(self.target_kT/self.mass) #variance of Boltzmann distrubution velocities
+
+      energy_tracker = physics.PotentialEnergyTracker(self.positions, self.epsilon, self.sigma,
+                                                    self.bond_length, self.spring_constant)
+      PE = energy_tracker.get_total_potential_energy()
+      max_displacement_size = self.bond_length * random_scale
+      atom_indexes = rand.randint(low=0, high=self.n_atoms-1, size=n_steps)
+      displacements = rand.uniform(low=-max_displacement_size/2, high=max_displacement_size/2, size=(n_steps, 3))
+      for step in range(n_steps):
+         is_displacement_accepted = False
+         PE_change = energy_tracker.test_displacement(atom_indexes[step], displacements[step])
+         if PE_change < 0 or np.exp(-PE_change / self.target_kT) > rand.random():
+            is_displacement_accepted = True
+            energy_tracker.accept_last_displacement()
+            PE += PE_change
+            self.positions[atom_indexes[step]] += displacements[step]
+         
+         step_data.append({
+            'step': step,
+            'displacement_accepted': is_displacement_accepted,
+            'PE_total': PE,
+            'L_end_to_end': np.sum((self.positions[0] - self.positions[-1]) ** 2) ** 0.5,
+         })
+         self._logging_step(step, step_data, run_type='MMC', n_steps=n_steps, temperature=temperature)
+      
+      self.step_data[self.run] = pd.DataFrame(step_data)
+      self._log_run_data(run_type='MMC', n_steps=n_steps, temperature=temperature)
+      self.dashboard.reset(self) if self.is_being_displayed else print(f'{n_steps:,} step MMC run completed')
+   
+   def display(self, display_interval: int = 1_000):
+      '''
+      Create an interactive dashboard that displays how the molecule's conformation and physical properties
+      change throughout the simulation. The dashboard can only be displayed in Jupyter Notebook. The dashboard
+      will update live if this method is called before a simulation run is started.
+
+      Parameters
+      ----------
+      display_interval : int
+         How many steps are run between each live display update. A larger interval will significantly speed
+         up longer runs. Note MMC runs have a 5x longer interval due to their higher run speed.
+      '''
+      assert display_interval % self.microstructure_logging_interval == 0,\
+             f'please select a display interval that is a multiple of {self.microstructure_logging_interval}'
+      self.display_interval = display_interval
+      try:
+         shell = get_ipython().__class__.__name__
+         if shell == 'ZMQInteractiveShell':
+            self.is_being_displayed = True
+            self.dashboard = display.SimulationDashboard(self)
+            self.dashboard.display(self)
+         else:
+            warnings.warn(f'This functionality is only available in a Jupyter Notebook. {shell} enviroment detected')
+      except NameError:
+         warnings.warn('This functionality is only available in a Jupyter Notebook')
+
+   def save(self, path: str) -> None:
+      '''
+      Save simulation object as a btye file.
+   
+      Parameters
+      ----------
+      path : str
+         File location where Simulation object will be stored.  
+      '''
+      with open(path, mode='wb') as file:
+         pickle.dump(self, file)
+
+   def _log_run_data(self, run_type: str, n_steps: int, temperature: float) -> None:
+      '''logs the final state of molecule after each run and stores it in the self.run_data dataframe'''
+      F_b, PE_b = physics.get_bonding_interactions(self.positions, self.bond_length, self.spring_constant)
+      F_nb, PE_nb = physics.get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+      current_state = {
+         'run': self.run,
+         'type': run_type,
+         'n_steps': n_steps,
+         'T': temperature,
+         'KE': physics.get_kintetic_energy(self.velocities, self.mass),
+         'PE_bonding': PE_b,
+         'PE_non_bonding': PE_nb,
+         'PE_total': PE_b + PE_nb, 
+         'F_rms': np.mean((F_b + F_nb)**2) ** 0.5,
+         'L_end_to_end': np.sum((self.positions[0] - self.positions[-1]) ** 2) ** 0.5, 
+      }
+      self.run_data = pd.concat([self.run_data, pd.DataFrame([current_state])])
+   
+   def _logging_step(self, step: int, step_data: list[dict], run_type: str, n_steps: int, temperature: float) -> None:
+      '''Saves microstructure and updates display at appropriate steps'''
+      if step % self.microstructure_logging_interval == 0: 
+         self.positions -= np.mean(self.positions, axis=0, keepdims=True) #centre molecule
+         self.microstructures[self.run][step] = pd.DataFrame(self.positions, columns=['x', 'y', 'z']).copy()
+      
+      if self.is_being_displayed == False:
+         return
+      display_interval = 5 * self.display_interval if run_type == 'MMC' else self.display_interval
+      if step % display_interval == 0: 
+         self.step_data[self.run] = pd.DataFrame(step_data)
+         self.dashboard.live_update(self, step, run_type, n_steps, temperature)
+
+def load_simulation(path: str) -> Simulation:
+   '''
+   Load in a simulation object from a file. For safety reasons, only load files you have created.
+   
+      Parameters
+      ----------
+      path : str
+         Simulation file location to be read in. 
+   '''
+   with open(path, mode='rb') as file:
+      return pickle.load(file)

imperial_materials_simulation-0.0.1/imperial_materials_simulation/physics.py

@@ -0,0 +1,146 @@
+'''
+Vectorised functions and classes for efficiently calculating kintetic energy, temperature, spring bonding
+interactions, and Lennard Jones long range interactions.
+'''
+import numpy as np
+#compiles functions for much higher speed when called many times. Limited compatibility with numpy
+import numba as nb 
+
+@nb.jit(nopython=True, fastmath=True)
+def get_kintetic_energy(velocities, mass) -> np.float64:
+    '''returns total kinetic energy of all atoms'''
+    return np.sum(mass/2 * velocities**2)
+
+@nb.jit(nopython=True, fastmath=True)
+def get_temperature(kinetic_energy: np.float64, n_atoms: int) -> np.float64:
+    '''returns the average temperature of all the atoms'''
+    kb = 8.617333262e-05
+    return 2 * kinetic_energy / (3 * (n_atoms-1) * kb)
+
+@nb.jit(nopython=True, fastmath=True) #fastmath increases float64 innaccuracy by 4x (1.1e-16 to 4.4e-16) which is acceptable here
+def get_bonding_interactions(positions: np.ndarray, equilibrium_bond_length: float, spring_constant: float) \
+                                -> list[np.ndarray, float]:
+    '''returns bonding forces for each atom and the total bonding potential of all atoms'''
+    bond_displacements = positions[1:] - positions[:-1]
+    bond_lengths = np.sum(bond_displacements**2, axis=1) ** 0.5
+    bond_lengths = bond_lengths.reshape(bond_lengths.shape[0], 1) #enables broadcasting in bond direction calculation
+    bond_extensions = bond_lengths - equilibrium_bond_length
+    bond_directions = bond_displacements / bond_lengths
+
+    bond_forces = -spring_constant * bond_extensions * bond_directions
+    atom_forces = np.zeros(shape=positions.shape)
+    atom_forces[:-1] -= bond_forces #each bond exerts a negative force on the left atom
+    atom_forces[1:] += bond_forces #each bond exerts a positive force on the right atom
+    total_bond_potential = np.sum(spring_constant/2 * (bond_extensions**2))
+    return atom_forces, total_bond_potential
+
+#numpy broadcasting can be used to replace the for loop and increase speed. This however requires boolean indexing
+#which is not supported by numba and so the proper numpy implementation actually ends up slower.
+@nb.jit(nopython=True, fastmath=True)
+def get_non_bonding_interactions(positions: np.ndarray, epsilon: float, sigma: float) -> list[np.ndarray, float]:
+    '''
+    returns the Lennard Jones (LJ) force for each atom and the total LJ potential of all atoms. This approximates
+    long range Van Der Valls attraction as well as the hard sphere repulsion of each atom to its more distant neighbours
+    (equilibrium LJ seperation is ~3x the equilibrium bond seperation) 
+    '''
+    n_atoms = positions.shape[0]
+    forces = np.zeros((n_atoms,3))
+    potential = 0.0
+    for i in range(n_atoms-1):
+        #displacements from atom i to its 3rd nearest neighbour and beyond (LJ models long range interactions). Looks
+        #like it ignores rightmost atoms but only find the displacement between relevant pairs once for efficiency 
+        displacements = positions[i+3:] - positions[i]
+        lengths = np.sum(displacements**2, axis=1) ** 0.5
+        lengths = lengths.reshape(lengths.shape[0], 1) #allows broadcasting in following calculations
+        directions = displacements / lengths
+        sixpowers = (sigma/lengths) ** 6
+        twelvepowers = sixpowers ** 2
+        potential += np.sum(epsilon * (twelvepowers - 2*sixpowers))
+
+        #forces exerted by atom i on its relevant neighbours
+        atom_forces = epsilon * 12/lengths * (twelvepowers - sixpowers) * directions
+        forces[i+3:] += atom_forces 
+        forces[i] -= np.sum(atom_forces, axis=0) #equal and opposite reaction on atom
+
+    return forces, potential 
+
+@nb.jit(nopython=True, fastmath=True)
+def get_energy_change(positions: np.ndarray, displacements: np.ndarray, lengths: np.ndarray, atom_index: int,
+                      displacement: np.ndarray, epsilon: float, sigma: float, equilibrium_bond_length: float,
+                      spring_constant: float) -> list[float, np.ndarray, np.ndarray, np.ndarray]:
+    '''
+    calculates only affected atom seperations to find how total potential energy changes. Really requires
+    you to draw out a mock displacement matrix and pick an atom index to understand the array indexing.
+    returns energy_change, new_positions, new_displacements, new_lengths
+    '''
+    i = atom_index
+    new_positions = positions.copy()
+    new_displacements = displacements.copy()
+    new_lengths = lengths.copy()
+    n_atoms = new_positions.shape[0]
+    energy_change = 0.0
+
+    new_positions[i] += displacement
+    new_displacements[i, i+1: ] = new_positions[i: i+1] - new_positions[i+1: ] 
+    new_lengths[i, i+1: ] = np.sum(new_displacements[i, i+1: ] ** 2, axis=1) ** 0.5
+    new_displacements[:i, i] = new_positions[:i] - new_positions[i: i+1]
+    new_lengths[:i, i] = np.sum(new_displacements[:i, i] ** 2, axis=1) ** 0.5
+
+    if i != 0:
+        extension = np.abs(lengths[i-1, i] - equilibrium_bond_length)
+        new_extension = np.abs(new_lengths[i-1, i] - equilibrium_bond_length)
+        energy_change += 0.5 * spring_constant * (new_extension**2 - extension**2)
+    if i != n_atoms-1:
+        extension = np.abs(lengths[i, i+1] - equilibrium_bond_length)
+        new_extension = np.abs(new_lengths[i, i+1] - equilibrium_bond_length)
+        energy_change += 0.5 * spring_constant * (new_extension**2 - extension**2)
+    
+    #Lennard Jones Potentials ignore 2 nearest neighbours of each atom
+    sixpowers = (sigma / lengths[i, i+3: ]) ** 6
+    new_sixpowers = (sigma / new_lengths[i, i+3: ]) ** 6
+    energy_change += epsilon * (np.sum(new_sixpowers**2 - 2*new_sixpowers) - np.sum(sixpowers**2 - 2*sixpowers))
+    if i > 1: #lengths[:i-2, i] returns unintended values if (i-2) is negative
+        sixpowers = (sigma / lengths[:i-2, i]) ** 6
+        new_sixpowers = (sigma / new_lengths[:i-2, i]) ** 6
+        energy_change += epsilon * (np.sum(new_sixpowers**2 - 2*new_sixpowers) - np.sum(sixpowers**2 - 2*sixpowers))
+
+    return energy_change, new_positions, new_displacements, new_lengths
+
+class PotentialEnergyTracker():
+    '''
+    Utility class for efficiently tracking how total potential energy (bonding + Lennard Jones non-bonding) changes
+    when a single atom is displaced.
+    '''
+
+    def __init__(self, positions: np.ndarray, epsilon: float, sigma: float, equilibrium_bond_length: float,
+                spring_constant: float) -> None:
+        'calculates key distances, lengths and total potential energy'
+        self.positions = positions
+        self.epsilon = epsilon
+        self.sigma = sigma
+        self.equilibrium_bond_length = equilibrium_bond_length
+        self.spring_constant = spring_constant
+        self.n_atoms = len(positions)
+
+        # (n_atoms x n_atoms) array where array[i, j] is the displacement going from j to i
+        self.displacements = self.positions.reshape(self.n_atoms, 1, 3) - self.positions.reshape(1, self.n_atoms, 3)
+        self.lengths = np.sum(self.displacements ** 2, axis=2) ** 0.5
+
+    def get_total_potential_energy(self):
+        '''return total potential energy of molecule'''
+        _, bonding_potential = get_bonding_interactions(self.positions, self.equilibrium_bond_length, self.spring_constant)
+        _, non_bonding_potential = get_non_bonding_interactions(self.positions, self.epsilon, self.sigma)
+        return bonding_potential + non_bonding_potential
+
+    def test_displacement(self, atom_index: int, displacement: np.ndarray) -> float:
+        '''stores temporary new positions, displacements, and lengths. Returns change in potential energy'''
+        result = get_energy_change(self.positions, self.displacements, self.lengths, atom_index, displacement, self.epsilon,
+                                   self.sigma, self.equilibrium_bond_length, self.spring_constant)
+        energy_change, self.new_positions, self.new_displacements, self.new_lengths = result
+        return energy_change
+
+    def accept_last_displacement(self) -> None:
+        '''replaces internal positions, displacements, and lengths with values from last test displacement'''
+        self.positions = self.new_positions
+        self.displacements = self.new_displacements
+        self.lengths = self.new_lengths

imperial_materials_simulation-0.0.1/imperial_materials_simulation.egg-info/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.1
+Name: imperial-materials-simulation
+Version: 0.0.1
+Summary: Molecular simulation tool made for the undergraduate materials science and engineering theory and simulation module at Imperial College London
+Home-page: https://github.com/AyhamSaffar/imperial_materials_simulation
+Author: Ayham Al-Saffar
+Requires-Python: ~=3.10
+Description-Content-Type: text/markdown
+
+This is a test to make sure this comes up

imperial_materials_simulation-0.0.1/imperial_materials_simulation.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+setup.py
+imperial_materials_simulation/__init__.py
+imperial_materials_simulation/display.py
+imperial_materials_simulation/main.py
+imperial_materials_simulation/physics.py
+imperial_materials_simulation.egg-info/PKG-INFO
+imperial_materials_simulation.egg-info/SOURCES.txt
+imperial_materials_simulation.egg-info/dependency_links.txt
+imperial_materials_simulation.egg-info/requires.txt
+imperial_materials_simulation.egg-info/top_level.txt

imperial_materials_simulation-0.0.1/imperial_materials_simulation.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

imperial_materials_simulation-0.0.1/imperial_materials_simulation.egg-info/requires.txt

@@ -0,0 +1,9 @@
+ipykernel
+ipympl
+ipywidgets
+matplotlib
+numba>=0.60.0
+numpy
+pandas
+py3dmol
+scipy

imperial_materials_simulation-0.0.1/imperial_materials_simulation.egg-info/top_level.txt

@@ -0,0 +1 @@
+imperial_materials_simulation

imperial_materials_simulation-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

imperial_materials_simulation-0.0.1/setup.py

@@ -0,0 +1,31 @@
+#python setup.py sdist bdist_wheel
+#twine upload --skip-existing dist/*
+#twine upload --skip-existing --repository testpypi dist/*
+
+from setuptools import setup, find_packages
+
+with open('README.md', mode='r') as file:
+    description = file.read()
+
+setup(
+    name = 'imperial_materials_simulation',
+    version = '0.0.1',
+    description = 'Molecular simulation tool made for the undergraduate materials science and engineering theory and simulation module at Imperial College London',
+    author = 'Ayham Al-Saffar',
+    url = 'https://github.com/AyhamSaffar/imperial_materials_simulation',
+    packages = find_packages(),
+    python_requires = '~=3.10',
+    install_requires = [
+        'ipykernel',
+        'ipympl',
+        'ipywidgets',
+        'matplotlib',
+        'numba>=0.60.0',
+        'numpy',
+        'pandas',
+        'py3dmol',
+        'scipy',
+    ],
+    long_description = description,
+    long_description_content_type = 'text/markdown',
+    )