abqsims.afm package

abqsims.afm.AFMForceContours(RF, XSectionData, YSectionData, surfacePos, surfaceDims, surfaceSize, tipDims, clearance, elasticProperties, contrast, m, **kwargs)

Function to plot a 2D force heatmap produced from simulation over the xz domain for single indenter and refereance force.

Parameters:

• RF (arr) – Array of reaction force in time on indentor reference point over scan position

• XSectionData – Scan and force data for scan cross section across X axis

• YSectionData (arr) – Scan and force data for scan cross section across Y axis

• surfacePos (arr) – Array of coordinates [x,y,z] of the sample surface to define surface mesh

• surfaceDims (arr) – Geometric parameters for defining surface dimensiond [width, height]

• surfaceSize (str) – Width of bins that subdivid xy domain of sample surface

• tipDims (list) – Geometric parameters for defining capped tip structure

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

• contrast (float) – Contrast between high and low values in AFM heat map (0-1)

Keywords Args:

• Noise (list) – If listed adds noise to AFM images [strength, mean, standard deviation]

• ImagePadding (float) – Black space / padding around image as percentage of dimensions of molecule extent

• SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.AFMSimulation(remote_server, remotePath, localPath, abqscripts, abqCommand, fileName, subData, pdb, rotation, surfaceApprox, indentorType, rIndentor, theta_degrees, tip_length, indentionDepth, forceRef, contrast, binSize, clearance, elasticProperties, meshSurface, meshBase, meshIndentor, timePeriod, timeInterval, **kwargs)

Final function to automate simulation.

User inputs all variables and all results are outputted. The user gets a optionally get a surface plot of scan positions. Produces a heatmap of the AFM image, and 3D plots of the sample surface for given force threshold.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]: - host (str): Hostname of the server to connect to - port (int): Server port to connect to - username (str): Username to authenticate as (defaults to the current local username) - password (str): Used for password authentication, None if ssh-key is used; is also used for private key decryption if passphrase is not given. - sshkey (str): Path to private key for keyexchange if password not used, None if not used - home (str): Path to home directory on remote server - scratch (str): Path to scratch directory on remote server

• remotePath (str) – Path to remote file/directory

• localPath (str) – Path to local file/directory

• abqscripts (list) – List of abaqus script files to transfer to remote server

• abqCommand (str) – Abaqus command to execute and run script

• fileName (str) – Base File name for abaqus input files

• subData (list) – Data for submission to serve queue [walltime, memory, cpus]

• pdbid (str) – PDB (or CSV) file name of desired biomolecule

• rotation (list) – Array of [xtheta, ytheta, ztheta] rotational angle around coordinate axis’

• surfaceApprox (float) – Percentage of biomolecule assumed to be not imbedded in base/ substrate. Range: 0-1

• indentorType (str) – String defining indentor type (Spherical or Capped)

• rIndentor (float) – Radius of spherical tip portion

• theta_degrees (float) – Principle conical angle from z axis in degrees

• tip_length (float) – Total cone height

• indentionDepth (float) – Maximum indentation depth into surface

• forceRef (float) – Threshold force to evaluate indentation contours at, mimics feedback force in AFM (pN)

• contrast (float) – Contrast between high and low values in AFM heat map (0-1)

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance(type – float) : Clearance above molecules surface indentor is set to during scan

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

• meshSurface (float) – Value of indentor mesh given as bin size for vertices of geometry in Angstrom (x10-10 m)

• meshBase (float) – Value of indentor mesh given as bin size for vertices of geometry in Angstrom (x10-10 m)

• meshIndentor (float) – Value of indentor mesh given as bin size for vertices of geometry in Angstrom (x10-10 m)

• timePeriod (float) – Total time length for ABAQUS simulation/ time step (T)

• timeInterval (float) – Time steps data sampled over for ABAQUS simulation/ time step (dt)

Keywords Args:

• Preprocess (bool) – If false skip preprocessing step of simulation {Default: True}

• CustomPDB – Extract data from local custom pd as opposed to from PDB online

• Submission (str) – Type of submission, whether submit pararlell scripts or single serial script for scan locations. Set submission as ‘serial’/ ‘paralell’ or False if no submisson {Default:’serial’}

• ProxyJump (obj) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

• Transfer (bool) – If false skip file transfer step of simulation {Default: True}

• Part (bool) – If false skip part creation step of simulation {Default: True}

• Input (bool) – If false skip input file creation step of simulation {Default: True}

• Batch (bool) – If false skip batch submission step of simulation {Default: True}

• Queue (bool) – If false skip queue completion step of simulation {Default: True}

• Analysis (bool) – If false skip odb analysis step of simulation {Default: True}

• Retrieval (bool) – If false skip data file retrivial from remote serve {Default: True}

• Postprocess (bool) – If false skip postprocessing step to produce AFM image from data {Default: True}

• ReturnData (bool) – If true returns simulation data to analysis {Default: False}

• DotPlot (bool) – If false skip surface plot of biomolecule and scan positions {Default: False}

• HSPlot (bool) – If false skip Hard Sphere AFM plot of biomolecule {Default: False}

• MoleculeView (bool) – If false skip interactive sphere model of biomolecule {Default: False}

• DataPlot (bool) – If false skip scatter plot of simulation data {Default: False}

• Noise (list) – If listed adds noise to AFM images [strength, mean, standard deviation]

• imagePadding (float) – Black space / padding around image as percentage of dimensions of molecule extent

• SaveImages (str) – Set if Contour images to be saved include kwarg specifying the file path to folder {Default: False}

Returns:

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• Y (arr) – 2D array of y coordinates over grid positions

• Z (arr) – 2D array of z coordinates of force contour over grid positions

• scanPos (arr) – Array of coordinates [x,y] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• baseDims (arr) – Geometric parameters for defining base/ substrate structure [width, height, depth]

abqsims.afm.BatchSubmission(remote_server, fileName, subData, clipped_scanPos, scanPos, scanDims, binSize, clearance, remotePath, **kwargs)

Function to create bash script for batch submission of input file, and run them on remote server.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

• fileName (str) – Base File name for abaqus input files

• subData (str) – Data for submission to serve queue [walltime, memory, cpus]

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule (can be clipped or full)

• scanPos (arr) – Array of coordinates [x,y] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance(type – float) : Clearance above molecules surface indentor is set to during scan

• remotePath (str) – Path to remote file/directory

Keywords Args:

• ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall. Defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

• Submission (‘serial’/ ‘paralell’) – Optional define whether single serial script or seperate paralell submission to queue {Default: ‘serial’}

abqsims.afm.ContourPlot(X, Y, Z, ErrorMask, scanDims, binSize, forceRef, contrast, pdb, **kwargs)

Function to plot force contor produced from simulation. Plots 3D wire frame image and a 2D AFM image.

Parameters:

• X (arr) – 2D array of x coordinates over grid positions

• Y (arr) – 2D array of y coordinates over grid positions

• Z (arr) – 2D array of z coordinates of force contour over grid positions

• ErrorMask (arr) – Boolean array specifying mask for all scan positions which errored in ABAQUS

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• forceRef (float) – Threshold force to evaluate indentation contours at (pN)

• contrast (float) – Contrast between high and low values in AFM heat map (0-1)

• pdb (str) – PDB (or CSV) file name of desired biomolecule

Keywords Args:

• Noise (list) – If listed adds noise to AFM images [strength, mean, standard deviation]

• ImagePadding (float) – Black space / padding around image as percentage of dimensions of molecule extent

• SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.DataAnalysis(U2, RF, force_data, scanPos, scanDims, binSize, clearance, waveLength, Nmax, courseGrain, rIndentor, elasticProperties, timeInterval, timePeriod, **kwargs)

Calculate a 2D force heatmap produced from simulation over the xz domain. Function for data analysis of simulation data. Producing arrays of Volume, FWHM,

Fourier series for contours of varying indentation force

Parameters:

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• force_data – Array of indentation forces to compare with

• scanPos (arr) – Array of coordinates [x,y] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance (float) – Clearance above molecules surface indentor is set to during scan

• waveLenght (float) – Principle waveLength for Fourier series

• Nmax (int) – Maximum number of terms in fourier series of force contour

• courseGrain (float) – Width of bins that subdivid xz domain of raster scanning/ spacing of the positions sampled over

• rIndentor – Indentor radius

• waveDims (list) – Geometric parameters for defining base/ substrate structure [wavelength, amplitude, width, Number of oscilations/ groups in wave]

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

• timeInterval (float) – Time steps data sampled over for ABAQUS simulation/ time step (dt)

• timePeriod (float) – Total time length for ABAQUS simulation/ time step (T)

Returns:

Array of indentation reference forces for force contours

structuralData: XZ (arr) : Z profile across X axis for given indentation forces YZ (arr) : Z profile across Y axis for given indentation forces DNAheight (arr) : DNA height for varying indentation force FWHM (arr) : Array of full width half maxima of contour for each indentation force [Nf, Nx] Volume (arr) : Volume under AFM image for varying indentation force AreaX (arr) : Area under topography for across X domain for each indentation force [Nf, Nx] AreaY (arr) : Area under topography for across Y domain for each indentation force [Nf, Ny] A (arr) : Array of Fourier components for contour for each indentation force [Nf, Ny]

XYSectionData: XYSection (arr) : 1D array of postions over x domain of scan positions ZSection (arr) : 1D array of postions over z domain of scan positions, discretised into bins of courseGrain value XYscanPos (arr) : Array of initial scan positions for indenter [Nxy, [x, z]] U2Section (arr) : Array of indentors y displacement in time over scan position [Nx, Nt] RFSection (arr) : Array of reaction force in time on indentor reference point over scan position [Nx, Nt] forceContour (arr) : 2D Array of coordinates for contours of constant force given by reference force across scan positons for reference force [Nf, Nxy, [x,z]] (With mask applied). forceGrid (arr) : 2D Array of force heatmap over xz domain of scan i.e. grid of xz positions with associated force for reference force [Nf, Nxy, Nz] (With mask applied). E_hertz (arr) : Array of fitted elastic modulus for each indentation force value over each scan positions [Nxy,Nt] E_contour (arr) : Array of fitted elastic modulus (upto clipped force) across the contour of the sample [Nxy] F (arr) : Array of interpolated force values over xz grid for all indentors and reference force [Nxy, Nz]

Return type:

indentationForce (arr)

abqsims.afm.DataPlot(scanPos, U2, RF, N)

Produces scatter plot of indentation depth and reaction force to visualise and check simulation data.

Parameters:

• scanPos (arr) – Array of coordinates [x,y] of scan positions to image biomolecule

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• N (int) – Number of frames in ABAQUS simulation/ time step

abqsims.afm.DataProcessing(clipped_RF, clipped_U2, scanPos, clipped_scanPos, clipped_ErrorMask, indentionDepth, timePeriod, timeInterval)

Function to load variables from files in current directory and process data from simulation in U2/RF files.

Process data from clipped scan positions to include full data range over all scan positions.

Parameters:

• clipped_RF – Array of indentors z displacement over clipped scan position

• clipped_U2 – Array of reaction force on indentor reference point over clipped scan positions

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule

• clipped_ErrorMask (arr) – Boolean array specifying mask for clipped scan positions which errored in ABAQUS

• indentionDepth (float) – Maximum indentation depth into surface

• timePeriod (float) – Total time length for ABAQUS simulation/ time step (T)

• timeInterval (float) – Time steps data sampled over for ABAQUS simulation/ time step (dt)

Returns:

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• ErrorMask (arr) – Boolean array specifying mask for all scan positions which errored in ABAQUS

• N (int) – Number of frames in ABAQUS simulation/ time step

abqsims.afm.DotPlot(atom_coord, atom_radius, atom_element, scanPos, clipped_scanPos, pdb, **kwargs)

Plot the molecules atoms surfaces and scan positions to visualise and check positions.

Parameters:

• atom_coord (arr) – Array of coordinates [x,y,z] for atoms in biomolecule

• atom_radius (dict) – Dictionary containing van der waals radii each the element in the biomolecule

• atom_element (arr) – Array of elements names(str) for atoms in biomolecule

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule

• pdb (str) – PDB (or CSV) file name of desired biomolecule

Keywords Args:

SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.ExportVariables(localPath, atom_coord, atom_element, atom_radius, clipped_scanPos, scanPos, scanDims, variables, baseDims, tipDims, indentorType, elasticProperties)

Export simulation variables as csv and txt files to load in abaqus python scripts.

Parameters:

• localPath (str) – Path to local file/directory

• atom_coord (arr) – Array of coordinates [x,y,z] for atoms in biomolecule

• atom_element (arr) – Array of elements names(str) for atoms in biomolecule

• atom_radius (dict) – Dictionary containing van der waals radii each the element in the biomolecule

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• variables (list) – List of simulation variables: [timePeriod, timeInterval, binSize, meshSurface, meshBase, meshIndentor, indentionDepth, surfaceHeight]

• baseDims (arr) – Geometric parameters for defining base/ substrate structure [width, height, depth]

• tipDims (list) – Geometric parameters for defining capped tip structure

• indentorType (str) – String defining indentor type (Spherical or Capped)

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

abqsims.afm.F_Hertz(U, E, rIndentor, elasticProperties)

Hertzian fit for indentation data

abqsims.afm.ForceContour2D(U2, RF, scanPos, forceRef)

Function to calculate contours/z heights of constant force in simulation data for given threshold force.

Parameters:

• U2 (arr) – Array of indentors y indentor position over scan ( As opposed to displacement into surface given from simulation and used elsewhere)

• RF (arr) – Array of reaction force on indentor reference point

• scanPos (arr) – Array of coordinates (x,z) of scan positions to image biomolecule [Nb,[x,z]]

• forceRef (float) – Threshold force to evaluate indentation contours at (pN)

Returns:

2D Array of coordinates for contours of constant force given by reference force across scan positons forceContourmask (arr) : 2D boolean array giving mask for force contour for zero values in which no reference force

Return type:

forceContour (arr)

abqsims.afm.ForceContours(U2, RF, forceRef, scanPos, scanDims, binSize, clearance)

Function to calculate contours/z heights of constant force in simulation data for given threshold force.

Parameters:

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• forceRef (float) – Threshold force to evaluate indentation contours at (pN)

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

Returns:

• X (arr) – 2D array of x coordinates over grid positions

• Y (arr) – 2D array of y coordinates over grid positions

• Z (arr) – 2D array of z coordinates of force contour over grid positions

abqsims.afm.ForceGrid2D(X, Z, U2, RF)

Function to produce force heat map over scan domain.

Parameters:

• X (arr) – 1D array of postions over x domain of scan positions

• Z (arr) – 1D array of postions over z domain of scan positions, discretised into bins of courseGrain value

• U2 (arr) – Array of indentors y indentor position over scan, discretised into bins of courseGrain value ( As opposed to displacement into surface given from simulation and used elsewhere)

• RF (arr) – Array of reaction force on indentor reference point

• scanPos (arr) – Array of coordinates (x,z) of scan positions to image biomolecule [Nb,[x,z]]

• courseGrain (float) – Width of bins that subdivid xz domain of raster scanning/ spacing of the positions sampled over

Keywords Args:

Symmetric – If false skip postprocessing step to ensure AFM image is symmetric about z-axis, instead produce image from raw data {Default: True}

Returns:

2D Array of force heatmap over xz domain of scan i.e. grid of xz positions with associated force [Nx,Nz] forceGridmask (arr) : 2D boolean array giving mask for force grid with exclude postions with no indentation data [Nx,Nz] forceContour (arr) : 2D Array of coordinates for contours of constant force given by reference force across scan positons forceContourmask (arr) : 2D boolean array giving mask for force contour for zero values in which no reference force

Return type:

forceGrid (arr)

abqsims.afm.ForceInterpolation(Xgrid, Zgrid, U2, RF, scanPos, rIndentor, elasticProperties, Nt)

Calculate a 2D force heatmap over the xz domain, produced from interpolated forces using Hertz model.

Parameters:

• Xgrid (arr) – 2D array/ grid of postions over xz domain of scan positions

• Zgrid (arr) – 2D array/ grid of postions over xz domain of scan positions

• U2 (arr) – Array of indentors y displacement in time over scan position and for one indenter [Ni, Nb, Nt]

• RF (arr) – Array of reaction force in time on indentor reference point over scan position and for one indenter [Nb, Nt]

• scanPos (arr) – Array of initial scan positions for one indenter [Nb, [x, z]]

• rIndentor (float) – Indentor radius of spherical tip portion varied for seperate simulations

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

• Nt (int) – Number of time steps

Returns:

Array of fitted elastic modulus for an indentation force value over each scan positions [Nb,Nt] E_contour (arr) : Array of fitted elastic modulus (upto clipped force) across the contour of the sample [Nb] F (arr) : Array of interpolated force values over xz grid for an indentors and reference force [Nb, Nz]

Return type:

E_hertz (arr)

abqsims.afm.ForceProfiles(scanPos, scanDims, binSize, XZ, YZ, indentationForce, force_data, cross_section_height_data, data_length, **kwargs)

abqsims.afm.Fourier(x, waveLength, *a)

Function to calculate Fourier Series for array of coefficence a

abqsims.afm.HardSphereAFM(scanPos, scanDims, binSize, clearance, contrast, pdb, **kwargs)

Plot the molecules atoms surfaces and scan positions to visualise and check positions.

Parameters:

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance (float) – Clearance above molecules surface indentor is set to during scan

• contrast (float) – Contrast between high and low values in AFM heat map (0-1)

• pdb (str) – PDB (or CSV) file name of desired biomolecule

Keywords Args:

• Noise (list) – If listed adds noise to AFM images [strength, mean, standard deviation]

• ImagePadding (float) – Black space / padding around image as percentage of dimensions of molecule extent

• SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.ImportVariables(localPath)

Import simulation geometry variables from csv files.

Parameters:

localPath (str) – Path to local file/directory

Returns:

• atom_coord (arr) – Array of coordinates [x,y,z] for atoms in biomolecule

• atom_element (arr) – Array of elements names(str) for atoms in biomolecule

• atom_radius (dict) – Dictionary containing van der waals radii each the element in the biomolecule

• variables (list) – List of simulation variables: [timePeriod, timeInterval, binSize, meshSurface, meshBase, meshIndentor, indentionDepth, surfaceHeight]

• baseDims (arr) – Geometric parameters for defining base/ substrate structure [width, height, depth]

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

abqsims.afm.LocalSubmission()

Submit Abaqus scripts locally

abqsims.afm.ManuscriptAFMContourPlot(U2, RF, scanPos, scanDims, binSize, clearance, ErrorMask, forceRef, contrast, pdb, **kwargs)

Function to plot force contor produced from simulation. Plots 3D wire frame image and a 2D AFM image.

Parameters:

• U2 (arr) – Array of indentors z displacement over scan position

• RF (arr) – Array of reaction force on indentor reference point

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance (float) – Clearance above molecules surface indentor is set to during scan

• ErrorMask (arr) – Boolean array specifying mask for all scan positions which errored in ABAQUS

• scanDims – Geometric parameters for defining scan dimensiond [width, height]

• binSize – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• forceRef (float) – Threshold force to evaluate indentation contours at (pN)

• contrast (float) – Contrast between high and low values in AFM heat map (0-1)

• pdb (str) – PDB (or CSV) file name of desired biomolecule

Keywords Args:

• Noise (list) – If listed adds noise to AFM images [strength, mean, standard deviation]

• ImagePadding (float) – Black space / padding around image as percentage of dimensions of molecule extent

• SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.ManuscriptDiagram(scanPos, scanDims, binSize, surfacePos, surfaceDims, surfaceSize, tipDims, **kwargs)

Plot the surfaces and scan positions to visualise and check positions.

Parameters:

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• surfacePos (arr) – Array of coordinates [x,y,z] of the sample surface to define surface mesh

• surfaceDims (arr) – Geometric parameters for defining surface dimensiond [width, height]

• surfaceSize (str) – Width of bins that subdivid xy domain of sample surface

• tipDims (list) – Geometric parameters for defining capped tip structure

Keywords Args:

SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.MolecularStructure(structure, rotation, tipDims, indentorType, binSize, surfaceApprox)

Extracts molecular data from structure class.

Returns array of molecules atomic coordinate and element names. Alongside, producing dictionary of element radii and calculating base dimensions. All distances given in Angstroms (x10-10 m).

Parameters:

• structure (class) – Class containing proteins structural data (Atom coords/positions and masses etc…)

• rotation (list) – Array of [x,y,z] rotational angle around coordinate axis’

• tipDims (list) – Geometric parameters for defining capped tip structure

• indentorType (str) – String defining indentor type (Spherical or Capped)

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• surfaceApprox (float) – Percentage of biomolecule assumed to be not imbedded in base/ substrate. Range: 0-1

Returns:

• atom_coord (arr) – Array of coordinates [x,y,z] for atoms in biomolecule

• atom_element (arr) – Array of elements names(str) for atoms in biomolecule

• atom_radius (dict) – Dictionary containing van der waals radii each the element in the biomolecule

• surfaceHeight (float) – Maximum height of biomolecule in z direction

• baseDims (arr) – Geometric parameters for defining base/ substrate structure [width, height, depth]

abqsims.afm.PDB(pdbid, localPath, **kwargs)

This function imports the relevant PDB file.

It takes care of the directory in which it is saved etc for the user, returning the structure and the view using a widget.

Parameters:

pdbid (str) – PDB (or CSV) file name of desired biomolecule

Keywords Args:

CustomPDB (str) – Extract data from local custom pd as opposed to from PDB online

Returns:

• structure (obj) – Class containing proteins structural data (Atom coords/positions and masses etc…)

• view (obj) – Class for visualising the protein

abqsims.afm.QueueCompletion(remote_server, **kwargs)

Function to check queue statis and complete when queue is empty.

Parameters:

remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

Keywords Args:

ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

abqsims.afm.RemoteCommand(remote_server, script, remotePath, command, **kwargs)

Function to execute a command/ script submission on the SSH server.

A new Channel is opened and the requested command is executed. The commands input and output streams are returned as Python file-like objects representing stdin, stdout, and stderr.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

• script (str) – Script to run via bash command

• remotePath (str) – Path to remote file/directory

• command (str) – Abaqus command to execute and run script

Keywords Args:

ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

abqsims.afm.RemoteFTPFiles(remote_server, files, remotePath, localPath, **kwargs)

Function to transfer files from directory on SSH server to local machine.

A new Channel is opened and the files are transfered. The function uses FTP file transfer.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

• files (str) – File to transfer

• remotePath (str) – Path to remote file/directory

• localPath (str) – Path to local file/directory

Keywords Args:

ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

abqsims.afm.RemoteSCPFiles(remote_server, files, remotePath, **kwargs)

Function to make directory and transfer files to SSH server.

A new Channel is opened and the files are transfered.The commands input and output streams are returned as Python file-like objects representing stdin, stdout, and stderr.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

• files (str/list) – File or list of file to transfer

• remotePath (str) – Path to remote file/directory

Keywords Args:

• ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

• path – Path to data files

abqsims.afm.RemoteSubmission(remote_server, remotePath, localPath, csvfiles, abqscripts, abqCommand, fileName, subData, scanPos, clipped_scanPos, scanDims, binSize, clearance, **kwargs)

Function to run simulation and scripts on the remote servers.

Files for variables are transfered, ABAQUS scripts are run to create parts and input files. A bash file is created and submitted to run simulation for batch of inputs. Analysis of odb files is performed and data transfered back to local machine. Using keyword arguments invidual parts of simulation previously completed can be skipped.

Parameters:

• remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

• remotePath (str) – Path to remote file/directory

• localPath (str) – Path to local file/directory

• csvfiles (list) – List of csv and txt files to transfer to remote server

• abqscripts (list) – List of abaqus script files to transfer to remote server

• abqCommand (str) – Abaqus command to execute and run script

• fileName (str) – Base File name for abaqus input files

• subData (str) – Data for submission to serve queue [walltime, memory, cpus]

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule (can be clipped or full)

• scanPos (arr) – Array of coordinates [x,y] of scan positions to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance (float) – Clearance above molecules surface indentor is set to during scan

Keywords Args:

• ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

• Submission (‘serial’/ ‘paralell’) – Type of submission, submit pararlell scripts or single serial script for scan locations {Default: ‘serial’}

• Transfer (bool) – If false skip file transfer step of simulation {Default: True}

• Part (bool) – If false skip part creation step of simulation {Default: True}

• Input (bool) – If false skip input file creation step of simulation {Default: True}

• Batch (bool) – If false skip batch submission step of simulation {Default: True}

• Queue (bool) – If false skip queue completion step of simulation {Default: True}

• Analysis (bool) – If false skip odb analysis step of simulation {Default: True}

• Retrieval (bool) – If false skip data file retrivial from remote serve {Default: True}

abqsims.afm.Remote_Terminal(remote_server, **kwargs)

Function to emulate cluster terminal.

Channel is opened and commands given are executed. The commands input and output streams are returned as Python file-like objects representing stdin, stdout, and stderr.

Parameters:

remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]

Keywords Args:

ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

abqsims.afm.Rotate(domain, rotation)

Rotate coordinates of a domain around each coordinate axis by angles given.

Parameters:

• domain (arr) – Array of [x,y,z] coordinates in domain to be rotated (Shape: (3) or (N,3) )

• rotation (list) – Array of [xtheta, ytheta, ztheta] rotational angle around coordinate axis: - xtheta(float): Angle in degrees for rotation around x axis (Row) - ytheta(float): Angle in degrees for rotation around y axis (Pitch) - ztheta(float): Angle in degrees for rotation around z axis (Yaw)

Returns:

rotate_domain (arr) – Rotated coordinate array

abqsims.afm.SSHconnect(remote_server, **kwargs)

Function to open ssh connecction to remote server.

A new Channel is opened and allows requested command to be executed in other functions. The function allows for ProxyJumpp/Port Forwarding/SSH Tunelling.

Parameters:

remote_server (list) – Contains varibles for remote server in list format [host, port, username, password, sshkey, home, scratch]: - host (str): Hostname of the server to connect to - port (int): Server port to connect to - username (str): Username to authenticate as (defaults to the current local username) - password (str): Used for password authentication, None if ssh-key is used; is also used for private key decryption if passphrase is not given. - sshkey (str): Path to private key for keyexchange if password not used, None if not used - home (str): Path to home directory on remote server - scratch (str): Path to scratch directory on remote server

Keywords Args:

ProxyJump (proxy_server) – Optional define whether to use a Proxy Jump to ssh through firewall; defines varibles for proxy server in list format [host, port, username, password, sshkey, home, scratch]

Returns:

ssh_client (obj) – SHH client object which allows for bash command execution and file transfer.

abqsims.afm.ScanGeometry(atom_coord, atom_radius, atom_element, indentorType, tipDims, baseDims, surfaceHeight, binSize, clearance, **kwargs)

Produces array of scan locations and corresponding heights/ tip positions above surface in Angstroms (x10-10 m).

Also return an array including only positions where tip interact with the sample. The scan positions are produced creating a rectangular grid over bases extent with widths bin size. Heights, at each position, are calculated by set tip above sample and calculating vertical distance between of tip and molecules surface over the indnenters area. Subsequently, the minimum vertical distance corresponds to the position where tip is tangential.

Parameters:

• atom_coord (arr) – Array of coordinates [x,y,z] for atoms in biomolecule

• atom_radius (dict) – Dictionary containing van der waals radii each the element in the biomolecule

• atom_element (arr) – Array of elements names(str) for atoms in biomolecule

• indentorType (str) – String defining indentor type (Spherical or Capped)

• tipDims (list) – Geometric parameters for defining capped tip structure

• baseDims (arr) – Geometric parameters for defining base/ substrate structure [width, height, depth]

• surfaceHeight (float) – Maximum height of biomolecule in z direction

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• clearance (float) – Clearance above molecules surface indentor is set to during scan

Returns:

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• clipped_scanPos (arr) – Array of clipped (containing only positions where tip and molecule interact) scan positions and initial heights [x,y,z] to image biomolecule

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

abqsims.afm.StructureAnalysis(X, Y, Z, scanDims, binSize, waveLength, Nmax)

Height, Volume, Cross-section, Profiles, FWHM, and Fourier

Calculate Fourier series components, Full Width Half Maxima and Volume for Force Contours of varying indentation force using splines

Parameters:

• X (arr) – 2D array of x coordinates over grid positions

• Y (arr) – 2D array of y coordinates over grid positions

• Z (arr) – 2D array of z coordinates of force contour over grid positions

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• Nmax (int) – Maximum number of terms in fourier series of force contour

Returns:

Z profile across X axis YZ : Z profile across Y axis DNAheight : DNA height FWHM (arr) : Array of full width half maxima of contour [Nx] Volume (arr) : Volume under AFM image AreaX (arr) : Area under topography for across X domain [Nx] AreaY (arr) : Area under topography for across Y domain [Ny] A (arr) : Array of Fourier components for contour [Ny]

Return type:

XZ

abqsims.afm.StructureAnalysisPlot(structuralData, indentationForce, force_data, force_height_data, FWHM_exp, AreaX_exp, **kwargs)

abqsims.afm.SurfacePlot(scanPos, scanDims, binSize, surfacePos, surfaceDims, surfaceSize, tipDims, **kwargs)

Plot the molecules atoms surfaces and scan positions to visualise and check positions.

Parameters:

• scanPos (arr) – Array of coordinates [x,y,z] of scan positions to image biomolecule and initial heights/ hard sphere boundary

• scanDims (arr) – Geometric parameters for defining scan dimensiond [width, height]

• binSize (float) – Width of bins that subdivid xy domain during raster scanning/ spacing of the positions sampled over

• surfacePos (arr) – Array of coordinates [x,y,z] of the sample surface to define surface mesh

• surfaceDims (arr) – Geometric parameters for defining surface dimensiond [width, height]

• surfaceSize (str) – Width of bins that subdivid xy domain of sample surface

• tipDims (list) – Geometric parameters for defining capped tip structure

Keywords Args:

SaveImages (str) – If Contour images to be saved include kwarg specifying the file path to folder

abqsims.afm.TipStructure(rIndentor, theta_degrees, tip_length)

Produce list of tip structural parameters.

Change principle angle to radian. Calculate tangent point where sphere smoothly transitions to cone for capped conical indentor.

Parameters:

• theta_degrees (float) – Principle conical angle from z axis in degrees

• rIndentor (float) – Radius of spherical tip portion

• tip_length (float) – Total cone height

Returns:

tipDims (list) – Geometric parameters for defining capped tip structure

abqsims.afm.YoungPlot(SectionData, rIndentor, elasticProperties, basePos, **kwargs)

Function to plot elastic modulus over scan position for each indentor.

Parameters:

• E_hertz (arr) – Array of fitted elastic modulus for each indentation force value over each scan positions for each indentor [Ni,Nb,Nt]

• indentorRadius (arr) – Array of indentor radii of spherical tip portion varied for seperate simulations

• elasticProperties (arr) – Array of surface material properties, for elastic surface [Youngs Modulus, Poisson Ratio]

• basePos (int) – Index of position along scan to consider vatioation in fitted E against force

abqsims.afm.Zconical(r, r0, r_int, z_int, theta, R, tip_length)

Calculates and returns spherically capped conical tip surface heights from radial position r.

Uses radial coordinate along xy plane from centre as tip is axisymmetric around z axis (bottom of tip set as zero point such z0 = R).

Parameters:

• r (float/1D arr) – xy radial coordinate location for tip height to be found

• r0 (float) – xy radial coordinate for centre of tip

• r_int (float) – xy radial coordinate of tangent point (point where sphere smoothly transitions to cone)

• z_int (float) – Height of tangent point, where sphere smoothly transitions to cone (defined for tip centred at spheres center, as calculations assume tip centred at indentors bottom the value must be corrected to, R-z_int)

• theta (float) – Principle conical angle from z axis in radians

• R (float) – Radius of spherical tip portion

• tip_length (float) – Total cone height

Returns:

Z (float/1D arr) – Height of tip at xy radial coordinate

abqsims.afm.Zspherical(r, r0, r_int, z_int, theta, R, tip_length)

Calculates and returns spherical tip surface heights from radial position r.

Uses radial coordinate along xy plane from centre as tip is axisymmetric around z axis (bottom of tip set as zero point such z0 = R).

Parameters:

• r (float/1D arr) – xy radial coordinate location for tip height to be found

• r0 (float) – xy radial coordinate for centre of tip

• r_int (float) – xy radial coordinate for tangent point (point where sphere smoothly transitions to cone)

• z_int (float) – Height of tangent point (point where sphere smoothly transitions to cone)

• theta (float) – Principle conical angle from z axis in radians

• R (float) – Radius of spherical tip portion

• tip_length (float) – Total cone height

Returns:

Z (float/1D arr) – Height of tip at xy radial coordinate