Allosteric Class

class Allosteric(graph, dim=2, params={'dashpot': 10.0, 'drag': 0.01, 'rfac': 0.05, 'stiffness': 1.0})

Bases: Elastic

Class to train an allosteric response in a random elastic network.

Parameters:

• graph (str or networkx.graph) – If string, filename of saved graph specifying the nodes and edge connections of the elastic network. If networkx.graph object, the graph to use.

• dim (int, optional) – The dimensionality of the system. Valid options are 2 and 3. If graph is a filename, the dimensionality will be read out from the file.

• params (dict, optional) –

  Specifies system parameters. Required keywords are :

  • ’rfac’: factor of shortest edge length that should correspond to node radius (used for plotting)

  • ’drag’: coefficient of isotropic drag

  • ’dashpot’: coefficient of dashpot damping at each edge

  • ’stiffness’: initial stiffness assigned to each edge spring

Variables:

• graph (networkx.graph) – Graph specifying the nodes and edges in the network. A stiffness, rest length, and “trainable” parameter are associated with each edge. A trainable edge will be updated during training.

• dim (int) – The dimensionality of the system. Valid options are 2 and 3.

• n (int) – Number of nodes in the network.

• ne (int) – Number of edges in the network.

• sources (list of dicts) –

  List of source node pairs. Each dict entry contains the following keys :

  • ’i’: Index of the first node in the pair.

  • ’j’: Index of the second node in the pair.

  • ’length’: The rest separation of the nodes.

  • ’phase’: +1 or -1, whether the source is stretched with positive or negative strain.

• targets (list of dicts) –

  List of target node pairs. Each dict entry contains the following keys :

  • ’i’: Index of the first node in the pair.

  • ’j’: Index of the second node in the pair.

  • ’length’: The rest separation of the nodes.

  • ’phase’: +1 or -1, whether the target is stretched with positive or negative strain.

• pts (ndarray) – (x,y) coordinates for each node in the system.

• degree (ndarray) – The degree (number of neighbors) of each node.

• Z (float) – The average coordination number, defined as 2*ne/nc, where nc is the number of nodes in the biggest connected component of the system.

• dZ (float) – The excess coordination, defined as Z - Ziso, where Ziso is the average coordination required for isostaticity (Ziso = 4 - 6/nc in 2D).

• traj (ndarray) – The simulated trajectory of the network produced after a call to the solve() routine.

• t_eval (ndarray) – The corresponding time at each simulated frame.

add_sources(ns=1, auto=True, boundary=False, seed=12, plot=True)

Add pairs of source nodes to the network.

If any two connected nodes are selected, the edge between them is removed.

Parameters:

• ns (int, optional) – The number of new pairs of source nodes to add. Default is 1.

• auto (bool, optional) – Whether to select sources automatically (True) or manually (False). Default is True.

• boundary (bool, optional) – Whether to restrict the choice of source nodes to the boundary. Default is False.

• seed (int, optional) – The random seed to use if selecting sources automatically.

• plot (bool, optional) – Whether to plot the network. Default is True. Will be set to True automatically for manual node selection.

add_targets(nt=1, auto=True, boundary=False, seed=12, plot=True)

Add pairs of target nodes to the network.

If any two connected nodes are selected, the edge between them is removed.

Parameters:

• ns (int, optional) – The number of new pairs of target nodes to add. Default is 1.

• auto (bool, optional) – Whether to select targets automatically (True) or manually (False). Default is True.

• boundary (bool, optional) – Whether to restrict the choice of target nodes to the boundary. Default is False.

• seed (int, optional) – The random seed to use if selecting targets automatically.

• plot (bool, optional) – Whether to plot the network. Default is True. Will be set to True automatically for manual node selection.

animate(spine=False, contour=False, outline=False, figsize=(5, 5), skip=1)

Animate the network after a simulation.

Parameters:

• spine (bool, optional) – Whether to plot only the spine of the network connecting the source and target nodes. Only used for 3D plotting. Default is false.

• contour (bool, optional) – Whether to plot the contour of the whole network. Helps with decluttering complicated networks when used with spine.

• outline (bool, optional) – Whether to outline nodes and edges with a black border. Default is False.

• figsize (tuple, optional) – The figure size.

• skip (int, optional) – Use every skip number of frames (skip=1 uses every frame).

Returns:

The resulting animation. In a jupyter notebook, the animation may be visualized with the import from IPython.display import HTML, and running HTML(ani.to_html5_video()).

Return type:

matplotlib.animation.FuncAnimation

color_plot(cmap, vmin, vmax, spine=False, contour=False, figsize=(5, 5), filename=None)

Plot the network with edges colored according to the bond stiffness.

Parameters:

• cmap (str or matplotlib.colors.Colormap) – The colormap to use.

• vmin (float) – The lower bound for the mapped values.

• vmax (float) – The upper bound for the mapped values.

• spine (bool, optional) – Whether to plot only the spine of the network connecting the source and target nodes. Only used for 3D plotting. Default is false.

• contour (bool, optional) – Whether to plot the contour of the whole network. Helps with decluttering complicated networks when used with spine.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

distribution_plot(kind='stiffness', vmin=0, vmax=2, nbins=25, figsize=(2.5, 2), filename=None)

Make a distribution plot of either bond stiffnesses or rest lengths.

Parameters:

• kind (str, optional) – Which quantity to plot. Valid options are ‘stiffness’ or ‘length’.

• vmin (float, optional) – The lower bound of the distribution.

• vmax (float, optional) – The upper bound of the distribution.

• nbins (int, optional) – The number of evenly-spaced bins to use.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

Returns:

Array of values whose distribution is plotted.

Return type:

ndarray

mode_plot(v, scale, arrows=True, disks=False, figsize=(5, 5), filename=None)

Plot a deformation mode (displacement) of the network.

Parameters:

• v (ndarray) – Unit displacement vector.

• scale (float) – Factor by which to scale the displacement values.

• arrows (bool, optional) – Whether to plot arrows at each node indicating the displacement direction, with size proportional to displacement magnitude.

• disks (bool, optional) – Whether to plot disks at each node colored according to displacement direction, with size proportional to displacement magnitude.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

mode_tile(vs, scale, filename=None)

Plot a collection of deformation modes (displacements) of the network.

Parameters:

• vs (ndarray) – Array of unit displacement vectors in each column.

• scale (float) – Factor by which to scale the displacement values.

• disks (bool, optional) – Whether to plot disks at each node colored according to displacement direction, with size proportional to displacement magnitude.

• filename (str, optional) – The name of the file for saving the plot.

plot(spine=False, contour=False, outline=False, figsize=(5, 5), filename=None)

Plot the network.

Parameters:

• spine (bool, optional) – Whether to plot only the spine of the network connecting the source and target nodes. Only used for 3D plotting. Default is False.

• contour (bool, optional) – Whether to plot the contour of the whole network. Helps with decluttering complicated networks when used with spine. Default is False.

• outline (bool, optional) – Whether to outline nodes and edges with a black border. Default is False.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

plot_source(ax, source)

Plot a source pair.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot.

• source (dict) – The source to visualize.

plot_target(ax, target)

Plot a target pair.

Parameters:

• ax (matplotlib.axes.Axes) – The axes on which to plot.

• target (dict) – The target to visualize.

reset_equilibrium()

Set the current network state to its equilibrium state.

rotate(spine=False, contour=False, skip=1)

Animate camera and light rotation about a static scene.

Parameters:

• spine (bool, optional) – Whether to plot only the spine of the network connecting the source and target nodes. Only used for 3D plotting. Default is false.

• contour (bool, optional) – Whether to plot the contour of the whole network. Helps with decluttering complicated networks when used with spine.

• skip (int, optional) – Use every skip number of frames (skip=1 uses every frame).

Returns:

The resulting animation. In a jupyter notebook, the animation may be visualized with the import from IPython.display import HTML, and running HTML(ani.to_html5_video()).

Return type:

matplotlib.animation.FuncAnimation

save(filename)

Save the network to a file.

Parameters:

filename (str) – The name of the text file to write.

strain(pair)

Compute the strain over time for a source or target pair.

Parameters:

pair (dict) – The source or target pair whose strain to compute.

Returns:

The strain over the course of the simulation.

Return type:

ndarray

strain_map(applied_args, figsize=(5, 5), filename=None)

Plot a map of the strain in the network due to input strains at the source or target.

Parameters:

• applied_args (tuple) – Simulation arguments: the source strain(s), target strain(s), and pinning stiffness.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

strain_plot(figsize=(3.5, 2), filename=None)

Make a line plot of source and target strains after a simulation.

Parameters:

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

strain_plot_thermal(es0, et0, figsize=(6, 4), filename=None)

Make a scatter plot of source and target strains.

Solid lines are used to denote reference source and target strain values.

Parameters:

• es0 (float) – Reference source strain.

• et0 (float) – Reference target strain.

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

time_lapse(figsize=(5, 5), filename=None)

Overlay all snapshots of a simulation.

Parameters:

• figsize (tuple, optional) – The figure size.

• filename (str, optional) – The name of the file for saving the plot.

write_job(filename, jobname, hours, cmd)

Write a shell script for submitting a job to SLURM.

Parameters:

• filename (str) – The name of the file to write to.

• jobname (str) – An identifier for the job.

• hours (int) – Number of hours to allocate for the job.

• cmd (str) – The command to be executed.

write_lammps_data(filename, title, applied_args)

Write the datafile of atoms and bonds for a simple LAMMPS simulation with harmonic bonds.

Parameters:

• filename (str) – The name of the file to write to.

• title (str) – Title string for the file.

• applied_args (tuple) – Simulation arguments: the source strain(s), target strain(s), and pinning stiffness.

write_lammps_data_learning(filename, title, applied_args, train=2, method='learning', eta=0.1, alpha=0.001, vmin=0.001, symmetric=False, dt=0.005)

Write the datafile of atoms and bonds for a LAMMPS simulation with custom coupled learning routine.

Parameters:

• filename (str) – The name of the file to write to.

• title (str) – Title string for the file.

• applied_args (tuple) – Simulation arguments: the source strain(s), target strain(s), and pinning stiffness.

• train (int, optional) – Training mode. 0 = no training, 1 = l-model, 2 = k-model.

• method (str, optional) – Training method to use. Options are ‘aging’ or ‘learning’.

• eta (float, optional) – The learning rate by which the clamped state target strain approaches the final desired strain.

• alpha (float, optional) – The aging rate.

• vmin (float, optional) – The smallest allowed value for each learning degree of freedom.

• symmetric (bool, optional) – Whether to introduce a symmetric state for training with a different set of boundary conditions. Default is False.

• dt (float, optional) – Integration step size.

write_lammps_input(filename, datafile, dumpfile, duration, frames, temp=0, method=None, symmetric=False, dt=0.005)

Write the input file for a LAMMPS simulation.

Parameters:

• filename (str) – The name of the file to write to.

• datafile (str) – The name of the datafile input, which will be overwritten on output. If path is included, must be relative to filename.

• dumpfile (str) – The name of the LAMMPS dumpfile for outputting node positions. If path is included, must be relative to filename.

• duration (float) – The final integration time.

• frames (int) – The number of output frames to produce (excluding initial frame).

• temp (float, optional) – The temperature setting, in LJ units. If zero (default), an athermal simulation is performed.

• method (str, optional) – The type of simulation to run. If left as default (None), bonds are not trainable and have no applied dashpots. Valid options are ‘aging’ or ‘learning’.

• symmetric (bool, optional) – Whether to introduce a symmetric state for training with a different set of boundary conditions. Default is False.

• dt (float, optional) – Integration step size.