mbtools analysis Documentation

mbtools Analysis

The analysis package is designed to help organise the many possible analysis routines that can be performed during a simulation. This documentation describes the basic user interface commands and then all of the possible analysis routines. Instructions on how to add a new analysis routine are given at the end of this document.

The following commands comprise the user interface to the analysis package.

At the start of a simulation all of the analysis that is to be performed is specified using the setup_analysis command. Each time you want the analysis performed a call to do_analysis should be made. One can then call print_averages to write results to file.

::mbtools::analysis::setup_analysis : -outputdir.arg -suffix.arg -iotype.arg -g.arg -str.arg

commands [./] A tcl list where each element of the list is a string specifying the name and complete argument list for a particular analysis to be carried out.
outputdir [./] The directory where analysis output files will be created
suffix [tmp] Suffix that will be appended to standard file names for analysis output
iotype [a] The iotype that will be used when opening files for analysis. For an explanation of the different iotypes see the documentation for the standard tcl command open
g [8]Number of grid points per side with which to divide the bilayer for height profile analyses
str [4.0] Distance of a tail bead from bilayer midplane beyond which a lipid is deemed to be a stray lipid.

Sets up the analysis package for a simulation run or analysis run that is about to be performed. This routine needs to be called before any analysis can be performed.

::mbtools::analysis::do_analysis :

Calls all of the analyze routines corresponding to commands setup in setup_analysis

Example:

do_analysis should be called only after setup_analysis has already been called. After that one simply uses;


	  ::mbtools::analysis::do_analysis

::mbtools::analysis::reset_averages :

Calls all of the resetav routines corresponding to commands setup in setup_analysis . These routines vary from command to command but they typically reset the storage and counter variables used for analysis results.

reset_averages is typically only called internally by print_averages

::mbtools::analysis::print_averages :

Calls all of the printav routines corresponding to commands setup in setup_analysis . These routines typically print results to a file buffer. After printing the reset_averages routine is called internally

Example:

print_averages should be called only after setup_analysis has already been called. After that one simply uses;


	  ::mbtools::analysis::print_averages

boxl : -verbose : output || time_vs_boxl

Simply obtains the box dimensions from expresso

clusters : -alipid.arg -verbose : output || time_vs_clust, sizehisto.[format %05d $time]

alipid [1.29] Value for the area per lipid to be used in a making a rough calculation of the area of clusters

Calls the espresso command analyze aggregation which groups molecules in the system into aggregates. Output to time_vs_clust is: maximum clusqqter size, minimum cluster size, average size of clusters including those of size 2 or greater ,standard deviation of clusters including those of size 2 or greater, number of clusters of size 2 or greater, total average cluster size, total cluster size std deviation, total number of clusters, length of the interface between clusters, standard deviation of the interface length, number of clusters for which length was calculate.

Additionally, at each call of print_averages the complete size histogram is printed to a file with the formatted name sizehisto.[format %05d $time]

density_profile : -nbins.arg -hrange.arg -beadtypes.arg -colloidmoltypes.arg -r.arg -nogrid -verbose : output || av_zprof

nbins [100] Number of slices into which the height range is divided for the purpose of calculating densities
hrange [6] The maximum vertical distance from the bilayer midplane for which to calculate densities. Note that the complete vertical range is therefore 2*hrange
beadtypes [0] A tcl list of the bead types for which to calculate a density profile
colloidmoltypes [] A tcl list of molecule types identifying the molecules which are colloids in the system. The default value is a null list
r [0] A tcl list of sphere radii corresponding to the radii for each colloid type in the system. If this is non-zero the density profile will be calculated in spherical shells about the colloids in the system identified via colloidmoltypes or if colloidmoltypes is not set then the system center of mass is assumed for the colloid/vesicle center
nogrid If this is set a grid mesh will not be used to refine the density profile calculation by taking into account vertical differences between mesh points

Calculates the number density of each of the beadtypes given in beadtypes as a function of the vertical distance from the bilayer midplane. Lipids are also sorted according to their orientation and assigned to upper or lower leaflets accordingly. Thus for a system with 3 beadtypes we would obtain 6 columns of output corresponding to 0 (lower) 1 (lower) 2 (lower) 2 (upper) 1 (upper) 0 (upper) where the number refers to the bead type and upper or lower refers to the bilayer leaflet.

energy : -verbose : output || time_vs_energy

Obtains the internal energies of the system from the analyze energy command of espresso.

flipflop : -verbose : output || time_vs_flip

Makes a call to the analyze get_lipid_orients command of espresso and compares this with a reference set of lipid orients obtained at the start of the simulation with setup_analysis . Based on this comparison the number of lipids which have flipped from their original positions is calculated

fluctuations : -verbose : output || powav.dat

Routine for calculating the power spectrum of fluctuations for a flat bilayer sheet. Uses the modes_2d routine in espresso to calculate the height function and perform the fft. See the documentation in the file fluctuations.tcl for detail on what is calculated and how to obtain a stiffness value from the resulting output.

Note that this routine causes a crash if it detects a large hole in the bilayer

localheights : -range.arg -nbins.arg -rcatch.arg -verbose : output || av_localh

range [1.0] Range of local height deviations over which to bin
nbins [100] Number of slices to divide up the height range into for the purposes of creating a profile
rcatch [1.9] The distance about a single lipid to use a starting value for finding the 6 closest neighbours

For each lipid we calculate its 6 nearest neighbours and then calculate the height difference between the central lipid and these neighbours. Taking these 6 values for each lipid we then create a histogram of number densities as a function of the height difference.

localorients : -range.arg -nbins.arg -verbose : output || av_localo

range [1.0] Range of orientation deviations to consider
nbins [100] Number of bins to use for histogram

Calculates the projection of the lipid orientation vector onto the xy plane for each lipid and then bins the absolute values of these vectors.

orient_order : -verbose : output || time_vs_oop

Calculates the orientational order parameter S for each lipid through a call to the espresso command analyze lipid_orient_order

pik1 : -verbose : output || time_vs_pik1

Calculates all 9 elements of the pressure tensor for the system through a call to the espresso command analyze pIK1

pressure : -verbose : output || time_vs_pressure

Calculates the isotropic pressure through a call to analyze pressure . Results are printed as a list of the various contributions in the following order: p_inst, total, ideal, FENE, harmonic, nonbonded. Where p_inst is the instantaneous pressure obtained directly from the barostat.

stray : -verbose : output || time_vs_stray

Calculates the number of stray lipids based on a call to analyze get_lipid_orients

distance : -verbose : output || time_vs_distance

Missing documentation

tiltangle : -verbose : output || time_vs_tiltangle

Missing documentation

Adding a new analysis routine

To add a new analysis routine you should create a new file called myanalysis.tcl which will contain all of your code. At the top of this file you should declare a namespace for your analysis code and include all of the internal variables inside that namespace as follows;


    namespace eval ::mbtools::analysis::myanalysis {
	variable av_myresult
	variable av_myresult_i
	variable f_tvsresult
	variable verbose
	
	namespace export setup_myanalysis
	namespace export analyze_myanalysis
	namespace export printav_myanalysis
	namespace export resetav_myanalisis
    }

Import your new file into the analysis package by adding a line like the following to the analysis.tcl file.


    source [file join [file dirname [info script]] myanalysis.tcl]

You then need to implement the following essential functions within your new namespace.

::mbtools::analysis::myanalysis::setup_myanalysis { args } Typically you would use this function to initialise variables and open files. Called by ::mbtools::analysis::setup_analysis . Arguments are allowed.
::mbtools::analysis::myanalysis::printav_myanalysis { void } This function should print results to a file. Called by ::mbtools::analysis::print_averages . Arguments are not allowed.
::mbtools::analysis::myanalysis::analyze_myanalysis { void } This function performs the actual analysis and should update the storage and averaging variables Called by ::mbtools::analysis::do_analysis . Arguments are not allowed.
::mbtools::analysis::myanalysis::resetav_myanalysis { void } This function should update averages and reset variables accordingly depending on your requirements. Called by ::mbtools::analysis::reset_averages . Arguments are not allowed.

If any of these functions is not implemented the program will probably crash.