Atomic and group contributions
One of the interesting features of Minimum-Distance distributions is that they can be naturally decomposed into the atomic or group contributions. Simply put, if a MDDF has a peak at a hydrogen-bonding distance, it is natural to decompose that peak into the contributions of each type of solute or solvent atom to that peak.
To obtain the atomic contributions of an atom or group of atoms, the contributions function is provided. For example, in a system composed of a protein and water, we would have defined the solute and solvent using:
using PDBTools, ComplexMixtures
+atoms = readPDB("system.pdb")
+protein = select(atoms,"protein")
+water = select(atoms,"water")
+solute = Selection(protein,nmols=1)
+solvent = Selection(water,natomspermol=3)The MDDF calculation is executed with:
trajectory = Trajectory("trajectory.dcd",solute,solvent)
+results = mddf(trajectory)Atomic contributions in the result data structure
The results data structure contains the decomposition of the MDDF into the contributions of every type of atom of the solute and the solvent. These data is available at the results.solute_atom and results.solvent_atom arrays:
julia> results.solute_atom
+50×1463 Array{Float64,2}:
+ 0.0 0.0 0.0 … 0.0 0.0 0.0
+ 0.0 0.0 0.0 … 0.0 0.0 0.0
+ ...
+ 0.0 0.14245 0.0 … 0.0 0.0 0.0
+ 0.0 0.0 0.0 … 0.0 0.0 0.0
+
+julia> results.solvent_atom
+50×3 Array{Float64,2}:
+ 0.0 0.0 0.0
+ 0.0 0.0 0.0
+ ...
+ 0.26087 0.26087 0.173913
+ 0.25641 0.0854701 0.170940Here, 50 is the number of bins of the histogram, whose distances are available at the results.d vector.
It is expected that for a protein most of the atoms do not contribute to the MDDF, and that all values are zero at very short distances, smaller than the radii of the atoms.
The three columns of the results.solvent_atom array correspond to the thee atoms of the water molecule in this example. The sequence of atoms correspond to that of the PDB file, but can be retrieved with:
julia> solvent.names
+3-element Array{String,1}:
+ "OH2"
+ "H1"
+ "H2"Therefore, if the first column of the results.solvent_atom vector is plotted as a function of the distances, one gets the contributions to the MDDF of the Oxygen atom of water. For example, here we plot the total MDDF and the Oxygen contributions:
using Plots
+plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
+plot!(results.d,results.solvent_atom[:,1],label="OH2",linewidth=2)
+plot!(xlabel="Distance / Å",ylabel="MDDF")
Selecting groups by atom names or indexes
To plot the contributions of the hydrogen atoms of water to the total MDDF, we have to select the two atoms, named H1 and H2. The contributions function provides several practical ways of doing that, with or without the use of PDBTools.
The contributions function receives three parameters:
- The
soluteorsolventdata structure, created withSelection. - The array of atomic contributions (here
results.solute_atomorresults.solvent_atom), corresponding to the selection in 1. - A selection of a group of atoms within the molecule of interest, provided as described below.
Selecting by indexes within the molecule
To select simply by the index of the atoms of the molecules, just provide a list of indexes to the contributions function. For example, to select the hydrogen atoms, which are the second and third atoms of the water molecule, use:
julia> indexes = [ 2, 3 ]
+julia> h_contributions = contributions(solvent,R.solvent_atom,indexes)
+500-element Array{Float64,1}:
+ 0.0
+ 0.0
+ ⋮
+ 0.7742706465861815
+ 0.8084139794974875Plotting both the oxygen (index = 1) and hydrogen contributions results in:
Selecting by atom name
The exact same plot above could be obtained by providing lists of atom names instead of indexes to the contributions function:
oxygen = ["OH2"]
+o_contributions = contributions(solvent,R.solvent_atom,oxygen)
+hydrogens = ["H1","H2"]
+h_contributions = contributions(solvent,R.solvent_atom,hydrogens)The above plot can be obtained with:
using Plots
+plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
+plot!(results.d,o_contributions,label="OH2",linewidth=2)
+plot!(results.d,h_contributions,label="Hydrogen atoms",linewidth=2)
+plot!(xlabel="Distance / Å",ylabel="MDDF")General selections using PDBTools
More interesting and general is to select atoms of a complex molecule, like a protein, using residue names, types, etc. Here we illustrate how this is done by providing selection strings to contributions to obtain the contributions to the MDDF of different types of residues of a protein to the total MDDF.
For example, if we want to split the contributions of the charged and neutral residues to the total MDDF distribution, we could use to following code. Here, solute refers to the protein.
charged_residues = PDBTools.select(atoms,"charged")
+charged_contributions = contributions(solute,R.solute_atom,charged_residues)
+
+neutral_residues = PDBTools.select(atoms,"neutral")
+neutral_contributions = contributions(solute,R.solute_atom,neutral_residues)The charged and neutral outputs are vectors containing the contributions of these residues to the total MDDF. The corresponding plot is:
plot(results.d,results.mddf,label="Total MDDF",linewidth=2)
+plot!(results.d,charged_contributions,label="Charged residues",linewidth=2)
+plot!(results.d,neutral_contributions,label="Neutral residues",linewidth=2)
+plot!(xlabel="Distance / Å",ylabel="MDDF")Resulting in:
Note here how charged residues contribute strongly to the peak at hydrogen-bonding distances, but much less in general. Of course all selection options could be used, to obtain the contributions of specific types of residues, atoms, the backbone, the side-chains, etc.
+
+
+
+
+
+
+
+
+
+
+![](\"../figures/mddf.png\")
","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"Thus, this plot was obtained with the following code:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"using Plots\nplot(results.d,results.mddf,xlabel=\"d/A\",ylabel=\"mddf(d) / L/mol\") ","category":"page"},{"location":"results/#Kirkwood-Buff-integral:-results.kb","page":"Results","title":"Kirkwood-Buff integral: results.kb","text":"","category":"section"},{"location":"results/","page":"Results","title":"Results","text":"The results.kb vector will contain the Kirkwood-Buff integral computed as a function of the minimum-distance to the solute. For properly sampled simulations, it is expected to converge at large distances. ","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"julia> results.kb\n500-element Array{Float64,1}:\n 0.0\n -0.3249356504752985\n -2.9804719721525\n ⋮\n 0.72186381783\n 1.13624162115","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"A typical plot of results.kb as a function of results.d will look like:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"![](\"../figures/kb.png\")
","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"Thus, this plot was obtained with the following code:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"using Plots\nplot(results.d,results.kb,xlabel=\"d/A\",ylabel=\"mddf(d) / L/mol\") ","category":"page"},{"location":"results/#Units","page":"Results","title":"Units","text":"","category":"section"},{"location":"results/","page":"Results","title":"Results","text":"The distance is assumed to be in Å, as this is the most common distance units in molecular simulations. The coordinates of the atoms are assumed be provided in Å. \nThe minimum-distance distribution function is unit-less, since it is the ratio of the density at each distance divided by an ideal-gas density.\nThe Kirkwood-Buff integrals are returned in cm³ mol⁻¹, if the coordinates were provided in Å.","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"warning: Warning\nIf the coordinates are not in Å, the calculation will proceed normally, but the units of the KB integrals, which has units of volume per mol, should be converted to conform the length unit provided. ","category":"page"},{"location":"results/#Coordination-number-and-other-data","page":"Results","title":"Coordination number and other data","text":"","category":"section"},{"location":"results/","page":"Results","title":"Results","text":"Obtaining the MDDF involves the computation of some intermediate properties that are frequently useful for additional solution structure analysis. In particular, the coordination numbers are computed. For example, the coordination number as a function from the distance to the solute can be retrieved from a Results data structure with:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"coordination_number = results.coordination_number","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"and this data can be plotted against the distances by:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"plot(result.d,results.coordination_number)","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"The coordination number of subgroups can also be obtained, as explained in the Coordination number section.","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"The complete data available is:","category":"page"},{"location":"results/","page":"Results","title":"Results","text":"Parameter Meaning Type of value Comment\nd Vector of distances of the histograms. Vector{Float64} To be used as the x coordinate on plotting any of the data.\nmd_count Non-normalized count of minimum distances at each d. Vector{Float64} This is the number of minimum distances found at each histogram bin, without normalization. Usually this is not interesting to analyze, because it is dependent on the bin size.\nmd_count_random Number of minimum distances found at each histogram bin for the random distribution. Vector{Float64} This is the normalization required to convert the md_count array into the minimum-distance distribution.\ncoordination_number Cumulative number of sites found for each histogram distance. Vector{Float64} This is the coordination number, that is, the number of sites found cumulative up to each distance, without any normalization.\ncoordination_number_random Cumulative site count for the random distribution. Vector{Float64} Usually not interesting for analysis.\nmddf The final distribution function. Vector{Float64} This is the MDDF computed (md_count normalized by md_count_random). It is the main result of the calculation.\nkb The final Kirkwood-Buff integral. Vector{Float64} This is the final KB integral, as a function of the integration distance from the solute. Computed as coordination_number - coordination_number_random\nsolute_atom Atomic contributions of the solute. Matrix{Float64} This is a matrix with nbins lines and solute.natomspermol columns, containing the atomic contributions of each solute atom to the complete MDDF.\nsolvent_atom Atomic contributions of the solvent. Matrix{Float64} This is a matrix with nbins lines and solvent.natomspermol columns, containing the atomic contributions of each solvent atom to the complete MDDF.\ndensity.solute Density (concentration) of the solute in the complete simulation box. Float64 In units of molecules/textrmAA^3\ndensity.solvent Density (concentration) of the solvent in the complete simulation box. Float64 In units of molecules/textrmAA^3\ndensity.solvent_bulk Density (concentration) of the solute in the bulk region. Float64 In units of molecules/textrmAA^3\nvolume Volume measures. Volume Contains the total volume of the simulation, the bulk volume, the volume of the solute domain and the shell volume of each bin of the histogram. These are computed by numerical integration from the random distributions.\nfiles List of files read. Vector{String} \nweights Weights of each file in the final counts. Vector{Float64} If the trajectories have different lengths or number of frames, the weights are adapted accordingly.\n ","category":"page"},{"location":"results/#Other-Result-parameters-available-which-are-set-at-Options:","page":"Results","title":"Other Result parameters available which are set at Options:","text":"","category":"section"},{"location":"results/","page":"Results","title":"Results","text":"Parameter Meaning Type of value Comment\nnbins Number of bins of the histograms. Int \ndbulk Distance from solute of bulk solution. Float64 \ncutoff Maximum distance to be considered for histograms. Float64 \nautocorrelation The solute is the same as the solvent? Bool Automatically set if solute == solvent.\nsolute Properties of the solute SolSummary Contains the number of atoms, number of atoms per molecule and number of molecules of the solute.\nsolvent Properties of the solvent. SolSummary Contains the number of atoms, number of atoms per molecule and number of molecules of the solvent.\nirefatom This is a reference atom that is used to generate random rotations and translations internally. Int Counts of the distributions for this atom are performed automatically to obtain radial (or proximal) distribution functions. Can be used for testing purposes.\nrdf_count This is the md_count minimum distance count of irefatom. Vector{Float64} This corresponds to the conventional radial distribution function if the solute contains only one atom.\nrdf_count_random Minimum distance of irefatom count for the random distribution. Vector{Float64} \nrdf Distribution function computed from the irefatom distribution. It is a conventional rdf if the solvent has only one atom. Vector{Float64} \nkb_rdf Kirkwood-Buff integral computed from the irefatom distribution. Vector{Float64} This must converge, at long distances, to the same value as kb, and can be used for testing.\noptions Calculation options. Options Carries (some redundant) options set by the user.\nlastframe_read Last frame read from the trajectory. Int \nn_frames_read Number of frames read from the trajectory. Int Can differ from lastframe_read if stride != 1\n ","category":"page"},{"location":"help/#Help-entries","page":"Help entries","title":"Help entries","text":"","category":"section"},{"location":"help/","page":"Help entries","title":"Help entries","text":"Modules=[ComplexMixtures]","category":"page"},{"location":"help/#ComplexMixtures.CMTypes","page":"Help entries","title":"ComplexMixtures.CMTypes","text":"Internal structure or function, interface may change.\n\nUnion of types to define an isaprox for testing.\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.ChemFile","page":"Help entries","title":"ComplexMixtures.ChemFile","text":"struct ChemFile{T<:(AbstractVector)} <: Trajectory\n\nStructure to contain a trajectory as read by Chemfiles.jl\n\nfilename::String\nformat::AbstractString\nstream::ComplexMixtures.Stream{<:Chemfiles.Trajectory}\nnframes::Int64\nsolute::Selection\nsolvent::Selection\nx_solute::Vector{T} where T<:(AbstractVector)\nx_solvent::Vector{T} where T<:(AbstractVector)\nunitcell::StaticArraysCore.MMatrix{3, 3, Float64, 9}\nnatoms::Int64\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.ChemFile-Tuple{String, Selection, Selection}","page":"Help entries","title":"ComplexMixtures.ChemFile","text":"ChemFile(filename::String, solute::Selection, solvent::Selection;format=\"\" , T::Type = SVector{3,Float64})\n\nFunction open will set up the IO stream of the trajectory, fill up the number of frames field and additional parameters if required.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.Density","page":"Help entries","title":"ComplexMixtures.Density","text":"mutable struct Density\n\nStructure to contain the density values obtained from the calculation.\n\nsolute::Float64: Default: 0.0\nsolvent::Float64: Default: 0.0\nsolvent_bulk::Float64: Default: 0.0\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.MinimumDistance","page":"Help entries","title":"ComplexMixtures.MinimumDistance","text":"struct MinimumDistance\n\nInternal structure or function, interface may change.\n\nExtended help\n\nThis structure contains the information, for each molecule, of if it is within the cutoff distance of the solute, the atom indexes of the associated minimum distance, the distance, and a label to mark if the reference atom of the molecule is within the cutoff distance of the solute.\n\nThe lists of minimum-distances are stored in arrays of type Vector{MinimumDistance}. The index of this vector corresponds to the index of the molecule in the original array.\n\nwithin_cutoff::Bool\ni::Int64\nj::Int64\nd::Float64\nref_atom_within_cutoff::Bool\nd_ref_atom::Float64\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.NamdDCD","page":"Help entries","title":"ComplexMixtures.NamdDCD","text":"struct NamdDCD{T<:(AbstractVector)} <: Trajectory\n\nStructure to contain the data of a trajectory in NAMD/DCD format.\n\nfilename::String\nstream::ComplexMixtures.Stream{<:FortranFiles.FortranFile}\nnframes::Int64\nsolute::Selection\nsolvent::Selection\nx_solute::Vector{T} where T<:(AbstractVector)\nx_solvent::Vector{T} where T<:(AbstractVector)\nlastatom::Int64\nunitcell_read::Vector{Float64}\nx_read::Vector{Float32}\ny_read::Vector{Float32}\nz_read::Vector{Float32}\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.NamdDCD-Tuple{String, Selection, Selection}","page":"Help entries","title":"ComplexMixtures.NamdDCD","text":"NamdDCD(filename::String, solute::Selection, solvent::Selection;T::Type = SVector{3,Float64})\n\nThis function initializes the structure above, returning the data and the vectors with appropriate lengths.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.Options","page":"Help entries","title":"ComplexMixtures.Options","text":"struct Options\n\nStructure that contains the detailed input options.\n\nfirstframe::Int64: Default: 1\nlastframe::Int64: Default: -1\nstride::Int64: Default: 1\nirefatom::Int64: Default: -1\nn_random_samples::Int64: Default: 10\nbinstep::Float64: Default: 0.02\ndbulk::Float64: Default: 10.0\ncutoff::Float64: Default: 10.0\nusecutoff::Bool: Default: false\nlcell::Int64: Default: 1\nGC::Bool: Default: true\nGC_threshold::Float64: Default: 0.1\nseed::Int64: Default: 321\nStableRNG::Bool: Default: false\nnthreads::Int64: Default: 0\nsilent::Bool: Default: false\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.OutputFiles","page":"Help entries","title":"ComplexMixtures.OutputFiles","text":"Internal structure or function, interface may change.\n\nmutable struct OutputFiles\n\nStructure to contain the names of the output files.\n\noutput::String\nsolute_atoms::String\nsolvent_atoms::String\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.Overview","page":"Help entries","title":"ComplexMixtures.Overview","text":"Internal structure or function, interface may change.\n\nmutable struct Overview\n\nStructure that is used to dispatch the show of a overview.\n\nR::Result\ndomain_molar_volume::Float64: Default: 0.0\ndensity::ComplexMixtures.Density: Default: Density()\nsolvent_molar_volume::Float64: Default: 0.0\nsolvent_molar_volume_bulk::Float64: Default: 0.0\nsolute_molar_volume::Float64: Default: 0.0\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.PDBTraj","page":"Help entries","title":"ComplexMixtures.PDBTraj","text":"struct PDBTraj{T<:(AbstractVector)} <: Trajectory\n\nStructure to contain PDB trajectories. Frames must be separated by \"END\", and with periodic cell sizes in the \"CRYST1\" field, for each frame.\n\nThis structure and functions can be used as a template to implement the reading of other trajectory formats. \n\nfilename::String\nstream::ComplexMixtures.Stream{<:IOStream}\nnframes::Int64\nunitcell::StaticArraysCore.MMatrix{3, 3, Float64, 9}\nsolute::Selection\nsolvent::Selection\nx_solute::Vector{T} where T<:(AbstractVector)\nx_solvent::Vector{T} where T<:(AbstractVector)\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.PDBTraj-Tuple{String, Selection, Selection}","page":"Help entries","title":"ComplexMixtures.PDBTraj","text":"PDBTraj(pdbfile::String, solute::Selection, solvent::Selection;T::Type = SVector{3,Float64})\n\nFunction open will set up the IO stream of the trajectory, fill up the number of frames field and additional parameters if required \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.Result","page":"Help entries","title":"ComplexMixtures.Result","text":"mutable struct Result{T<:VecOrMat{Float64}}\n\nStructure to contain the results of the MDDF calculation.\n\nnbins::Int64\ndbulk::Float64\ncutoff::Float64\nd::Vector{Float64}: Default: zeros(nbins)\nmd_count::Vector{Float64}: Default: zeros(nbins)\nmd_count_random::Vector{Float64}: Default: zeros(nbins)\ncoordination_number::Vector{Float64}: Default: zeros(nbins)\ncoordination_number_random::Vector{Float64}: Default: zeros(nbins)\nmddf::Vector{Float64}: Default: zeros(nbins)\nkb::Vector{Float64}: Default: zeros(nbins)\nautocorrelation::Bool\nsolvent::ComplexMixtures.SolSummary\nsolute::ComplexMixtures.SolSummary\nsolute_atom::VecOrMat{Float64}: Default: zeros(nbins, solute.natomspermol)\nsolvent_atom::VecOrMat{Float64}: Default: zeros(nbins, solvent.natomspermol)\nrdf_count::Vector{Float64}: Default: zeros(nbins)\nrdf_count_random::Vector{Float64}: Default: zeros(nbins)\nsum_rdf_count::Vector{Float64}: Default: zeros(nbins)\nsum_rdf_count_random::Vector{Float64}: Default: zeros(nbins)\nrdf::Vector{Float64}: Default: zeros(nbins)\nkb_rdf::Vector{Float64}: Default: zeros(nbins)\ndensity::ComplexMixtures.Density: Default: Density()\nvolume::ComplexMixtures.Volume: Default: Volume(nbins)\noptions::Options\nirefatom::Int64\nlastframe_read::Int64\nnframes_read::Int64\nfiles::Vector{String}\nweights::Vector{Float64}\n\nThe Result{Vector{Float64}} parametric type is necessary only for reading the JSON3 saved file. \n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.Selection","page":"Help entries","title":"ComplexMixtures.Selection","text":"struct Selection\n\nStructure that contains the information about the solute and solvent molecules.\n\nnatoms::Int64\nnmols::Int64\nnatomspermol::Int64\nindex::Vector{Int64}\nimol::Vector{Int64}\nnames::Vector{String}\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.SolSummary","page":"Help entries","title":"ComplexMixtures.SolSummary","text":"Internal structure or function, interface may change.\n\nstruct SolSummary\n\nStructures to contain the details of a solute or solvent to store in the results of the MDDF calculation.\n\nnatoms::Int64\nnmols::Int64\nnatomspermol::Int64\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.Trajectory","page":"Help entries","title":"ComplexMixtures.Trajectory","text":"Trajectory(filename::String, solute::Selection, solvent::Selection; format::String = \"\", chemfiles = false)\n\nTrajectory constructor data type. \n\nDefaults to reading with the Chemfiles infrastructure, except for DCD and PDB trajectory files, if the \"PDBTraj\" option is provided.\n\nSee memory issue (https://github.com/chemfiles/Chemfiles.jl/issues/44)\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.Units","page":"Help entries","title":"ComplexMixtures.Units","text":"Internal structure or function, interface may change.\n\nstruct Units\n\nUnit conversions.\n\nmole::Any: Default: 6.022140857e23\nAngs3tocm3::Any: Default: 1.0e24\nAngs3toL::Any: Default: 1.0e27\nAngs3tocm3permol::Any: Default: mole / Angs3tocm3\nAngs3toLpermol::Any: Default: mole / Angs3toL\nSitesperAngs3tomolperL::Any: Default: Angs3toL / mole\n\n\n\n\n\n","category":"type"},{"location":"help/#ComplexMixtures.Volume","page":"Help entries","title":"ComplexMixtures.Volume","text":"mutable struct Volume\n\nStructures to contain the volumes obtained from calculations.\n\ntotal::Float64\nbulk::Float64\ndomain::Float64\nshell::Vector{Float64}\n\n\n\n\n\n","category":"type"},{"location":"help/#Base.isapprox-Union{Tuple{T}, Tuple{T, T}} where T<:Union{Options, ComplexMixtures.SolSummary, ComplexMixtures.Density, ComplexMixtures.Volume, Result}","page":"Help entries","title":"Base.isapprox","text":"Base.isapprox(r1::T, r2::T; debug=false) where T <: CMTypes\n\nInternal structure or function, interface may change.\n\nFunction to test if two runs offered similar results. Mostly used in the package testing routines.\n\n\n\n\n\n","category":"method"},{"location":"help/#Base.merge-Tuple{Vector{<:Result}}","page":"Help entries","title":"Base.merge","text":"merge(r::Vector{Result})\n\nThis function merges the results of MDDF calculations obtained by running the same analysis on multiple trajectories, or multiple parts of the same trajectory. It returns a Result structure of the same type, with all the functions and counters representing averages of the set provided weighted by the number of frames read in each Result set.\n\n\n\n\n\n","category":"method"},{"location":"help/#Base.write-Tuple{Result, String, Selection, Selection}","page":"Help entries","title":"Base.write","text":"write(R::ComplexMixtures.Result, filename::String, solute::Selection, solvent::Selection)\n\nFunction to write the final results to output files as simple tables that are human-readable and easy to analyze with other software\n\nIf the solute and solvent selections are provides, pass on the atom names.\n\n\n\n\n\n","category":"method"},{"location":"help/#Base.write-Tuple{Result, String}","page":"Help entries","title":"Base.write","text":"write(R::ComplexMixtures.Result, filename::String; \n solute_names::Vector{String} = [\"nothing\"], \n solvent_names::Vector{String} = [\"nothing\"])\n\nOptional passing of atom names.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.VMDselect-Tuple{String, String}","page":"Help entries","title":"ComplexMixtures.VMDselect","text":"VMDselect(inputfile::String, selection::String; vmd=\"vmd\", srcload=nothing)\n\nSelect atoms using vmd selection syntax, with vmd in background\n\nReturns the list of index (one-based) and atom names\n\nFunction to return the selection from a input file (topology, coordinates, etc), by calling VMD in the background.\n\nThe srcload argument can be used to load a list of scripts before loading the input file, for example with macros to define custom selection keywords.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.contributions-Tuple{Selection, Matrix{Float64}, Vector{Int64}}","page":"Help entries","title":"ComplexMixtures.contributions","text":"contributions(s::Selection, atom_contributions::Matrix{Float64}, selection)\n\nExtract the contribution of a given atom type selection from the solute or solvent atomic contributions to the MDDF.\n\ns here is the solute or solvent selection (type ComplexMixtures.Selection) atom_contributions is the R.solute_atom or R.solvent_atom arrays of the Result structure, and the last argument is the selection of atoms from the solute to be considered, given as a list of indexes, list of atom names, vector of PDBTools.Atoms, or a PDBTools.Residue. \n\nExtended help\n\nFor selections of one molecule, the function has an additional keyword option first_atom_is_ref that is false by default. If set to true, the index first atom of the selection is considered as a reference atom. For example if a solute has 100 atoms, but its first atom in the PDB file is number 901, the selection of indexes [1, 2, 3] will refer to atoms with indexes [901, 902, 903].\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.coordination_number","page":"Help entries","title":"ComplexMixtures.coordination_number","text":"coordination_number(trajectory::Trajectory, options::Options)\n\nComputes the coordination numbers for each solute molecule in the trajectory, given the Trajectory. This is an auxiliary function of the ComplexMixtures package, which is used to compute coordination numbers when the normalization of the distribution is not possible or needed. \n\nThe output is a Result structure, which contains the data as the result of a call to mddf, except that all counters which require normalization of the distribution will be zero. In summary, this result data structure can be used to compute the coordination numbers, but not the MDDF, RDF, or KB integrals.\n\nExamples\n\njulia> trajectory = Trajectory(\"./trajectory.dcd\",solute,solvent);\n\njulia> results = mddf(trajectory);\n\njulia> coordination_numbers = coordination_number(trajectory);\n\n\n\n\n\n","category":"function"},{"location":"help/#ComplexMixtures.coordination_number-2","page":"Help entries","title":"ComplexMixtures.coordination_number","text":"coordination_number(R::Result) = R.coordination_number\ncoordination_number(R::Result, group_contributions::Vector{Float64})\ncoordination_number(s::Selection, atom_contributions::Matrix{Float64}, R::Result, group)\n\nComputes the coordination number of a given group of atoms from the solute or solvent atomic contributions to the MDDF. If no group is defined (first call above), the coordination number of the whole solute or solvent is returned.\n\nIf the group_contributions to the mddf are computed previously with the contributions function, the result can be used to compute the coordination number by calling coordination_number(R::Result, group_contributions).\n\nOtherwise, the coordination number can be computed directly with the second call, where:\n\ns is the solute or solvent selection (type ComplexMixtures.Selection)\n\natom_contributions is the R.solute_atom or R.solvent_atom arrays of the Result structure\n\nR is the Result structure,\n\nand the last argument is the selection of atoms from the solute to be considered, given as a list of indexes, list of atom names, or a selection following the syntax of PDBTools, or vector of PDBTools.Atoms, or a PDBTools.Residue\n\nExamples\n\nIn the following example we compute the coordination number of the atoms of residue 50 (of the solute) with the solvent atoms of TMAO, as a function of the distance. Finally, we show the average number of TMAO molecules within 5 Angstroms of residue 50. The findlast(<(5), R.d) part of the code below returns the index of the last element of the R.d array that is smaller than 5 Angstroms.\n\nPrecomputing the group contributions Using the contributions function\n\nusing ComplexMixtures, PDBTools\npdb = readPDB(\"test/data/NAMD/structure.pdb\");\nR = load(\"test/data/NAMD/protein_tmao.json\");\nsolute = Selection(PDBTools.select(pdb, \"protein\"), nmols=1);\nresidue50 = PDBTools.select(pdb, \"residue 50\");\n# Compute the group contributions to the MDDF\nresidue50_contribution = contributions(solute, R.solute_atom, residue50);\n# Now compute the coordination number\nresidue50_coordination = coordination_number(R, residue50_contribution)\n# Output the average number of TMAO molecules within 5 Angstroms of residue 50\nresidue50_coordination[findlast(<(5), R.d)]\n\nWithout precomputing the group_contribution\n\nusing ComplexMixtures, PDBTools\npdb = readPDB(\"test/data/NAMD/structure.pdb\");\nR = load(\"test/data/NAMD/protein_tmao.json\");\nsolute = Selection(PDBTools.select(pdb, \"protein\"), nmols=1);\nresidue50 = PDBTools.select(pdb, \"residue 50\");\n# Compute the coordination number\nresidue50_coordination = coordination_number(solute, R.solute_atom, R, group)\n# Output the average number of TMAO molecules within 5 Angstroms of residue 50\nresidue50_coordination[findlast(<(5), R.d)]\n\n\n\n\n\n","category":"function"},{"location":"help/#ComplexMixtures.coordination_number_frame!-Tuple{Result, CellListMap.PeriodicSystems.AbstractPeriodicSystem, ComplexMixtures.Buffer, Options, Any}","page":"Help entries","title":"ComplexMixtures.coordination_number_frame!","text":"coordination_number_frame!(R::Result, system::AbstractPeriodicSystem, buff::Buffer, options::Options, RNG)\n\nInternal structure or function, interface may change.\n\nComputes the coordination numbers for a single frame. Modifies the data in the R (type Result) structure.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.eulermat-Tuple{Any, Any, Any, String}","page":"Help entries","title":"ComplexMixtures.eulermat","text":"eulermat(beta, gamma, theta, deg::String)\n\nInternal structure or function, interface may change.\n\nThis routine was added because it defines the rotation in the \"human\" way, an is thus used to set the position of the fixed molecules. deg can only be \"degree\", in which case the angles with be considered in degrees. If no deg argument is provided, radians are used.\n\nThat means: beta is a counterclockwise rotation around x axis. gamma is a counterclockwise rotation around y axis. theta is a counterclockwise rotation around z axis.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.finalresults!-Tuple{Result, Options, Trajectory}","page":"Help entries","title":"ComplexMixtures.finalresults!","text":"finalresults!(R::Result, options::Options, trajectory::Trajectory)\n\nInternal structure or function, interface may change.\n\nFunction that computes the final results of all the data computed by averaging according to the sampling of each type of data, and converts to common units.\n\nComputes also the final distribution functions and KB integrals.\n\nThis function modified the values contained in the R data structure.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.gr-Tuple{Result}","page":"Help entries","title":"ComplexMixtures.gr","text":"gr(R::Result) = gr(R.d,R.rdf_count,R.density.solvent_bulk,R.options.binstep)\n\nIf a Result structure is provided without further details, use the rdf count and the bulk solvent density.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.gr-Tuple{Vector{Float64}, Vector{Float64}, Float64, Float64}","page":"Help entries","title":"ComplexMixtures.gr","text":"gr(r::Vector{Float64}, count::Vector{Float64}, density::Float64, binstep::Float64)\n\nComputes the radial distribution function from the count data and the density.\n\nThis is exactly a conventional g(r) if a single atom was chosen as the solute and solvent selections.\n\nReturns both the g(r) and the kb(r)\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.grid3D-Tuple{}","page":"Help entries","title":"ComplexMixtures.grid3D","text":"grid3D(solute,solute_atoms,mddf_result,output_file; dmin=1.5, ddax=5.0, step=0.5)\n\nThis function builds the grid of the 3D density function and fills an array of mutable structures of type Atom, containing the position of the atoms of grid, the closest atom to that position, and distance. \n\nsolute is a ComplexMixtuers.Selection, defining the solute. solute_atoms is the corresponding vector of PDBTools.Atoms, and mddf_result is the result of a mddf_result calculation with the correspondign solute. \n\ndmin and dmax define the range of distance where the density grid will be built, and step defines how fine the grid must be. Be aware that fine grids involve usually a very large (hundreds of thousands points).\n\nAll parameters can be provides as keyword parameters.\n\nExample\n\njulia> using ComplexMixtures, PDBTools\n\njulia> pdb = readPDB(\"./system.pdb\");\n\njulia> R = ComplexMixtures.load(\"./results.json\");\n\njulia> protein = select(pdb,\"protein\");\n\njulia> solute = ComplexMixtures.Selection(protein,nmols=1);\n\njulia> grid = ComplexMixtures.grid3D(solute=solute, solute_atoms=protein, mddf_result=R, output_file=\"grid.pdb\");\n\n\ngrid will contain a vector of Atoms with the information of the MDDF at each grid point, and the same data will be written in the grid.pdb file. This PDB file can be opened in VMD, for example, and contain in the beta field the contribution of each protein residue to the MDDF at each point in space relative to the protein, and in the occupancy field the distance to the protein. Examples of how this information can be visualized are provided in the user guide of ComplexMixtures. \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.itype-Tuple{Int64, Int64}","page":"Help entries","title":"ComplexMixtures.itype","text":"itype(iatom::Int, natomspermol::Int)\n\nInternal structure or function, interface may change.\n\nGiven the index of the atom in the vector of coordinates of the solute or the solvent, returns the type of the atom, that is, the index of this atom within the molecule (goes from 1 to natomspermol)\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.load-Tuple{String}","page":"Help entries","title":"ComplexMixtures.load","text":"load(filename::String)\n\nFunction to load the json saved results file into the Result data structure.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.mddf","page":"Help entries","title":"ComplexMixtures.mddf","text":"mddf(trajectory::Trajectory, options::Options)\n\nFunction that computes the minimum-distance distribution function, atomic contributions, and KB integrals, given the Trajectory structure of the simulation and, optionally, parameters given as a second argument of the Options type. This is the main function of the ComplexMixtures package. \n\nExamples\n\njulia> trajectory = Trajectory(\"./trajectory.dcd\",solute,solvent);\n\njulia> results = mddf(trajectory);\n\nor, to set some custom optional parameter,\n\njulia> options = Options(lastframe=1000);\n\njulia> results = mddf(trajectory,options);\n\n\n\n\n\n","category":"function"},{"location":"help/#ComplexMixtures.mddf_frame!-Tuple{Result, CellListMap.PeriodicSystems.AbstractPeriodicSystem, ComplexMixtures.Buffer, Options, Any}","page":"Help entries","title":"ComplexMixtures.mddf_frame!","text":"mddf_frame!(R::Result, system::AbstractPeriodicSystem, buff::Buffer, options::Options, RNG)\n\nInternal structure or function, interface may change.\n\nComputes the MDDF for a single frame. Modifies the data in the R (type Result) structure.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.minimum_distances!-Tuple{CellListMap.PeriodicSystems.AbstractPeriodicSystem, Result, Int64}","page":"Help entries","title":"ComplexMixtures.minimum_distances!","text":"minimum_distances!(system::CellListMap.PeriodicSystem, R::Result)\n\nInternal structure or function, interface may change.\n\nFunction that computes the list of distances of solvent molecules to a solute molecule. It updates the lists of minimum distances. \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.mol_index-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.mol_index","text":"mol_index(i_atom, natomspermol) = (i_atom-1) ÷ natomspermol + 1\n\nInternal structure or function, interface may change.\n\nExtended help\n\nSets the index of the molecule of an atom in the simples situation, in which all molecules have the same number of atoms. \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.mol_range-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.mol_range","text":"mol_range(imol, n_atoms_per_molecule)\n\nInternal structure or function, interface may change.\n\nGiven the index and the number of atoms per molecule, returns the range of indices of of an array of coordinates that corresponds to the molecule.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.move!-Union{Tuple{T}, Tuple{AbstractVector{T}, T, Any, Any, Any}} where T<:(StaticArraysCore.SVector)","page":"Help entries","title":"ComplexMixtures.move!","text":"move!(x::AbstractVector, newcm::AbstractVector,beta, gamma, theta)\n\nInternal structure or function, interface may change.\n\nTranslates and rotates a molecule according to the desired input center of coordinates and Euler rotations modifyies the vector x.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.overview-Tuple{Result}","page":"Help entries","title":"ComplexMixtures.overview","text":"overview(R::Result)\n\nFunction that outputs the volumes and densities in the most natural units.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.random_move!-Tuple{AbstractVector{<:StaticArraysCore.SVector{3}}, Int64, CellListMap.PeriodicSystems.AbstractPeriodicSystem, Any}","page":"Help entries","title":"ComplexMixtures.random_move!","text":"random_move!(x_ref::AbstractVector{T}, \n irefatom::Int,\n system::AbstractPeriodicSystem,\n x_new::AbstractVector{T}, RNG) where {T<:SVector}\n\nInternal structure or function, interface may change.\n\nFunction that generates a new random position for a molecule.\n\nThe new position is returned in x_new, a previously allocated array.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.randomize_solvent!-Tuple{CellListMap.PeriodicSystems.AbstractPeriodicSystem, ComplexMixtures.Buffer, Int64, Result, Any}","page":"Help entries","title":"ComplexMixtures.randomize_solvent!","text":"randomize_solvent!(system, buff, n_solvent_in_bulk, options, RNG)\n\nInternal structure or function, interface may change.\n\nGenerate a random solvent distribution from the bulk molecules of a solvent\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.save-Tuple{Result, String}","page":"Help entries","title":"ComplexMixtures.save","text":"save(R::Result, filename::String)\n\nFunction to write the result data structure to a json file.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.setbin-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.setbin","text":"setbin(d,step)\n\nInternal structure or function, interface may change.\n\nFunction that sets to which histogram bin a data point pertains simple, but important to keep consistency over all calls.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.setup_PeriodicSystem-Tuple{Trajectory, Options}","page":"Help entries","title":"ComplexMixtures.setup_PeriodicSystem","text":"setup_PeriodicSystem(trajectory::Trajectory, options::Options)\n\nInternal structure or function, interface may change.\n\nSetup the periodic system from CellListMap, to compute minimimum distances. The system will be setup such that xpositions corresponds to one molecule of the solute, and ypositions contains all coordinates of all atoms of the solvent. \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.shellradius-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.shellradius","text":"shellradius(i,step)\n\nInternal structure or function, interface may change.\n\nCompute the point in which the radius comprises half of the volume of the shell.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.sphereradiusfromshellvolume-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.sphereradiusfromshellvolume","text":"sphereradiusfromshellvolume(volume,step)\n\nInternal structure or function, interface may change.\n\nComputes the radius that corresponds to a spherical shell of a given volume.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.sphericalshellvolume-Tuple{Any, Any}","page":"Help entries","title":"ComplexMixtures.sphericalshellvolume","text":"sphericalshellvolume(i,step)\n\nInternal structure or function, interface may change.\n\nComputes the volume of the spherical shell defined within [(i-1)step,istep].\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.sum!-Tuple{Result, Result}","page":"Help entries","title":"ComplexMixtures.sum!","text":"sum!(R1::Result, R2::Result)\n\nInternal structure or function, interface may change.\n\nSum the counts of two Results structures, adding the result to the first structure as in R1 = R1 + R2.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.title-Tuple{Result, Selection, Selection}","page":"Help entries","title":"ComplexMixtures.title","text":"title(R::Result, solute::Selection, solvent::Selection)\ntitle(R::Result, solute::Selection, solvent::Selection, nspawn::Int)\n\nInternal structure or function, interface may change.\n\nPrint some information about the run.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.update_list!-Tuple{Any, Any, Any, Any, Any, Any, Vector{ComplexMixtures.MinimumDistance}}","page":"Help entries","title":"ComplexMixtures.update_list!","text":"update_list!(i, j, d2, iref_atom::Int, mol_index_i::F, isolute::Int, list::Vector{MinimumDistance{T}}) where {F<:Function, T}\n\nInternal structure or function, interface may change.\n\nFunction that updates a list of minimum distances given the indexes of the atoms involved for one pair within cutoff, for autocorrelations (such that the identity of isolute is needed)\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.update_list!-Tuple{Any, Any, Any, Any, Any, Vector{ComplexMixtures.MinimumDistance}}","page":"Help entries","title":"ComplexMixtures.update_list!","text":"update_list!(i, j, d2, iref_atom::Int, mol_index_i::F, list::Vector{MinimumDistance{T}}) where {F<:Function, T}\n\nInternal structure or function, interface may change.\n\nFunction that updates a list of minimum distances given the indexes of the atoms involved for one pair within cutoff.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.update_md-Tuple{ComplexMixtures.MinimumDistance, ComplexMixtures.MinimumDistance}","page":"Help entries","title":"ComplexMixtures.update_md","text":"update_md(md1::MinimumDistance{T}, md2::MinimumDistance{T}) where {T}\n\nInternal structure or function, interface may change.\n\nFunction that returns the updated minimum distance structure after comparing two structures associated with the same molecule.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.updatecounters!-Tuple{Result, CellListMap.PeriodicSystems.AbstractPeriodicSystem}","page":"Help entries","title":"ComplexMixtures.updatecounters!","text":"updatecounters!(R::Result, system::AbstractPeriodicSystem)\n\nInternal structure or function, interface may change.\n\nFunction that updates the minimum-distance counters in R\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.viewmol-Union{Tuple{T}, Tuple{Int64, Vector{T}, Int64}} where T","page":"Help entries","title":"ComplexMixtures.viewmol","text":"viewmol(i::Int, x::Vector{T}, n::Int) where T\n\nInternal structure or function, interface may change.\n\nReturns a view of a coordinate vector corresponding to the atoms of a molecule with index i. n is the number of atoms of the molecule.\n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.which_types-Tuple{Selection, Vector{Int64}}","page":"Help entries","title":"ComplexMixtures.which_types","text":"which_types(s::Selection, indexes::Vector{Int})\n\nInternal structure or function, interface may change.\n\nFunction that returns the list of the indexes of the types of the atoms in a selection. For example, if a selection corresponds to a solvent of water molecules: There are three types, 1, 2, and 3, corresponding to the three atoms of the water molecule. If the indexes provided are, for instance, 11, 12, and 13, corresponding to a water molecule, this function will return 1, 2 and 3.\n\nThis is used to get equivalent-atom contributions to the distribution functions. For example, the input indexes span all water molecules, the output of this function will be still the three indexes corresponding to the three types of atoms that exist in a water molecule. \n\nIt is not possible to compute the contribution of one individual water molecule if the distribution function was computed for all molecules. Thus, the necessity to identify the types of atoms involved in a selection. \n\n\n\n\n\n","category":"method"},{"location":"help/#ComplexMixtures.writexyz-Union{Tuple{T}, Tuple{Vector{T}, String}} where T<:(AbstractVector)","page":"Help entries","title":"ComplexMixtures.writexyz","text":"writexyz(x::Vector{T}, file::String) where T <: AbstractVector\n\nInternal structure or function, interface may change.\n\nPrint test xyz file.\n\n\n\n\n\n","category":"method"},{"location":"mddf/#Computing-the-Minimum-Distance-Distribution-Function","page":"Computing the MDDF","title":"Computing the Minimum-Distance Distribution Function","text":"","category":"section"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"The main function of the ComplexMixtures package actually computes the MDDF between the solute and the solvent chosen. ","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"It is run with the following command:","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"results = mddf(trajectory) ","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"The MDDF along with other results, like the corresponding KB integrals, are returned in the results data structure, which is described in the next section.","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"It is possible to tune several options of the calculation, by setting the Options data structure with user-defined values in advance. The most common parameters to be set by the user are probably dbulk and stride. ","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"dbulk defines the distance from the solute above which the user believes that the reference solute molecule does not significantly anymore the structure of the solvent. The default value is 10 Angstroms, but for large solvent molecules this might not be enough. To increase dbulk, use: ","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"options = Options(dbulk=15.)\nresults = mddf(trajectory,options)","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"stride defines if some frames will be skip during the calculation (for speedup). For example, if stride=5, only one in five frames will be considered. Adjust stride with: ","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"options = Options(stride=5)\nresults = mddf(trajectory,options)","category":"page"},{"location":"mddf/","page":"Computing the MDDF","title":"Computing the MDDF","text":"See the Options section for further details and other options to set.","category":"page"},{"location":"installation/#Installation","page":"Installation","title":"Installation","text":"","category":"section"},{"location":"installation/","page":"Installation","title":"Installation","text":"note: Note\nThis is a package written in Julia. We invite you to experiment with the language, but if you want to just call this package from Python, read the From Python section of the manual. Understanding all the features of the package requires reading the manual as whole. The syntaxes of using this package from Julia or Python are almost identical, and the motivation for using Python should be mostly the familiarity with further analsys tools, as the plotting packages. ","category":"page"},{"location":"installation/#Install-Julia","page":"Installation","title":"Install Julia","text":"","category":"section"},{"location":"installation/","page":"Installation","title":"Installation","text":"First you need to install the Julia language in your platform, from: http://julialang.org. Julia version 1.6 or greater is required. Using the juliaup tool is also a highly recommended way of installing and keeping Julia up to date.","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"tip: Tip\nNew to Julia? Julia is a modern high-level yet performant programming language. Some tips and a nice workflow for using it effectively can be found here. For this specific package, following a the step-by-step examples provided here after installing Julia should be enough. ","category":"page"},{"location":"installation/#Install-the-packages","page":"Installation","title":"Install the packages","text":"","category":"section"},{"location":"installation/","page":"Installation","title":"Installation","text":"Within Julia, to install the packages required for running the examples here you need to do:","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"julia> import Pkg\n\njulia> Pkg.add([\"ComplexMixtures\",\"Plots\",\"PDBTools\"])","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"Please read the recommended workflow below, for further information and to be sure to have a smoother experience.","category":"page"},{"location":"installation/#Recommended-workflow-for-reproducibility","page":"Installation","title":"Recommended workflow for reproducibility","text":"","category":"section"},{"location":"installation/#Create-an-environment","page":"Installation","title":"Create an environment","text":"","category":"section"},{"location":"installation/","page":"Installation","title":"Installation","text":"Once Julia is installed, we recommend to create an environment that will contain all the packages you may use for your analyses, including ComplexMixtures, in such a way that your results can always be reproduced and you don't get any version incompatibility.","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"We illustrate this by creating the \"MyNewPaper\" environment, which will be hosted in a simple directory,","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"mkdir /home/user/Documents/MyNewPaper","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"Then, start Julia and activate the environment that will be hosted there:","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"julia> import Pkg; Pkg.activate(\"/home/user/Documents/MyNewPaper\")\n Activating new project at `~/Documents/MyNewPaper`","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"and add to this environment the packages that your analyses will require:","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"julia> Pkg.add([\"ComplexMixtures\",\"PDBTools\",\"Plots\"])","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"That's it. Close Julia. Note that this created the files Manifest.toml and Project.toml in the MyNewPaper directory, which contain the information of packages and exact package versions you are using now on in this environment. Saving these files may be relevant for the future exact reproduction of your analyses. ","category":"page"},{"location":"installation/#Run-your-analysis-scripts-in-that-environment","page":"Installation","title":"Run your analysis scripts in that environment","text":"","category":"section"},{"location":"installation/","page":"Installation","title":"Installation","text":"Now, your analysis scripts, described in the next section in details, will look like: ","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"import Pkg; Pkg.activate(\"/home/user/Documents/MyNewPaper\")\n\nusing ComplexMixtures\nusing PDBTools\nusing Plots\n\n# etc ... ","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"And the script can be run with julia -t auto script.jl (where -t auto allows for multi-threading), or included in julia with julia> include(\"./scritp.jl\"), as described in the next section.","category":"page"},{"location":"installation/","page":"Installation","title":"Installation","text":"tip: Tip\nBy loading the package with using ComplexMixturesthe most common functions of the package become readily available by their direct name, for example mddf(...).If you don't want to bring the functions into the scope of your script, useimport ComplexMixturesThen, the functions of the package are called, for example, using ComplexMixtures.mddf(...). To avoid having to write ComplexMixtures all the time, define an accronym. For example:import ComplexMixtures as CM\nCM.mddf(...)","category":"page"},{"location":"contrib/#contributions","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"One of the interesting features of Minimum-Distance distributions is that they can be naturally decomposed into the atomic or group contributions. Simply put, if a MDDF has a peak at a hydrogen-bonding distance, it is natural to decompose that peak into the contributions of each type of solute or solvent atom to that peak. ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"To obtain the atomic contributions of an atom or group of atoms, the contributions function is provided. For example, in a system composed of a protein and water, we would have defined the solute and solvent using:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"using PDBTools, ComplexMixtures\natoms = readPDB(\"system.pdb\")\nprotein = select(atoms,\"protein\")\nwater = select(atoms,\"water\")\nsolute = Selection(protein,nmols=1)\nsolvent = Selection(water,natomspermol=3)","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The MDDF calculation is executed with:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"trajectory = Trajectory(\"trajectory.dcd\",solute,solvent)\nresults = mddf(trajectory)","category":"page"},{"location":"contrib/#Atomic-contributions-in-the-result-data-structure","page":"Atomic and group contributions","title":"Atomic contributions in the result data structure","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The results data structure contains the decomposition of the MDDF into the contributions of every type of atom of the solute and the solvent. These data is available at the results.solute_atom and results.solvent_atom arrays: ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"julia> results.solute_atom\n50×1463 Array{Float64,2}:\n 0.0 0.0 0.0 … 0.0 0.0 0.0\n 0.0 0.0 0.0 … 0.0 0.0 0.0\n ...\n 0.0 0.14245 0.0 … 0.0 0.0 0.0\n 0.0 0.0 0.0 … 0.0 0.0 0.0\n\njulia> results.solvent_atom \n50×3 Array{Float64,2}:\n 0.0 0.0 0.0 \n 0.0 0.0 0.0 \n ...\n 0.26087 0.26087 0.173913\n 0.25641 0.0854701 0.170940","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Here, 50 is the number of bins of the histogram, whose distances are available at the results.d vector.","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"It is expected that for a protein most of the atoms do not contribute to the MDDF, and that all values are zero at very short distances, smaller than the radii of the atoms.","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The three columns of the results.solvent_atom array correspond to the thee atoms of the water molecule in this example. The sequence of atoms correspond to that of the PDB file, but can be retrieved with:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"julia> solvent.names\n3-element Array{String,1}:\n \"OH2\"\n \"H1\"\n \"H2\"","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Therefore, if the first column of the results.solvent_atom vector is plotted as a function of the distances, one gets the contributions to the MDDF of the Oxygen atom of water. For example, here we plot the total MDDF and the Oxygen contributions: ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"using Plots\nplot(results.d,results.mddf,label=\"Total MDDF\",linewidth=2)\nplot!(results.d,results.solvent_atom[:,1],label=\"OH2\",linewidth=2)\nplot!(xlabel=\"Distance / Å\",ylabel=\"MDDF\")","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"![](\"../figures/oh2.png\")
","category":"page"},{"location":"contrib/#Selecting-groups-by-atom-names-or-indexes","page":"Atomic and group contributions","title":"Selecting groups by atom names or indexes","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"To plot the contributions of the hydrogen atoms of water to the total MDDF, we have to select the two atoms, named H1 and H2. The contributions function provides several practical ways of doing that, with or without the use of PDBTools. ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The contributions function receives three parameters: ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The solute or solvent data structure, created with Selection. \nThe array of atomic contributions (here results.solute_atom or results.solvent_atom), corresponding to the selection in 1.\nA selection of a group of atoms within the molecule of interest, provided as described below. ","category":"page"},{"location":"contrib/#Selecting-by-indexes-within-the-molecule","page":"Atomic and group contributions","title":"Selecting by indexes within the molecule","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"To select simply by the index of the atoms of the molecules, just provide a list of indexes to the contributions function. For example, to select the hydrogen atoms, which are the second and third atoms of the water molecule, use:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"julia> indexes = [ 2, 3 ]\njulia> h_contributions = contributions(solvent,R.solvent_atom,indexes)\n500-element Array{Float64,1}:\n 0.0\n 0.0\n ⋮\n 0.7742706465861815\n 0.8084139794974875","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Plotting both the oxygen (index = 1) and hydrogen contributions results in:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"![](\"../figures/h_and_oh2.png\")
","category":"page"},{"location":"contrib/#Selecting-by-atom-name","page":"Atomic and group contributions","title":"Selecting by atom name","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The exact same plot above could be obtained by providing lists of atom names instead of indexes to the contributions function:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"oxygen = [\"OH2\"]\no_contributions = contributions(solvent,R.solvent_atom,oxygen) \nhydrogens = [\"H1\",\"H2\"]\nh_contributions = contributions(solvent,R.solvent_atom,hydrogens)","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The above plot can be obtained with:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"using Plots\nplot(results.d,results.mddf,label=\"Total MDDF\",linewidth=2)\nplot!(results.d,o_contributions,label=\"OH2\",linewidth=2)\nplot!(results.d,h_contributions,label=\"Hydrogen atoms\",linewidth=2)\nplot!(xlabel=\"Distance / Å\",ylabel=\"MDDF\")","category":"page"},{"location":"contrib/#General-selections-using-PDBTools","page":"Atomic and group contributions","title":"General selections using PDBTools","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"More interesting and general is to select atoms of a complex molecule, like a protein, using residue names, types, etc. Here we illustrate how this is done by providing selection strings to contributions to obtain the contributions to the MDDF of different types of residues of a protein to the total MDDF. ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"For example, if we want to split the contributions of the charged and neutral residues to the total MDDF distribution, we could use to following code. Here, solute refers to the protein.","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"charged_residues = PDBTools.select(atoms,\"charged\")\ncharged_contributions = contributions(solute,R.solute_atom,charged_residues)\n\nneutral_residues = PDBTools.select(atoms,\"neutral\")\nneutral_contributions = contributions(solute,R.solute_atom,neutral_residues)","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The charged and neutral outputs are vectors containing the contributions of these residues to the total MDDF. The corresponding plot is: ","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"plot(results.d,results.mddf,label=\"Total MDDF\",linewidth=2)\nplot!(results.d,charged_contributions,label=\"Charged residues\",linewidth=2)\nplot!(results.d,neutral_contributions,label=\"Neutral residues\",linewidth=2)\nplot!(xlabel=\"Distance / Å\",ylabel=\"MDDF\")","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Resulting in:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"![](\"../figures/charged_and_neutral.png\")
","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Note here how charged residues contribute strongly to the peak at hydrogen-bonding distances, but much less in general. Of course all selection options could be used, to obtain the contributions of specific types of residues, atoms, the backbone, the side-chains, etc. ","category":"page"},{"location":"parallel/#Parallel-execution","page":"Parallel execution","title":"Parallel execution","text":"","category":"section"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"It is highly recommended to run MDDF calculations in parallel, using multiple processors of a single computer. To run the computation in parallel, initialize julia with the -t auto option:","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"julia -t auto","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"The computation will use a number of threads equal to the number of physical cores of the computer. The number of computation threads to be used can be set by the Options(nthreads=N) parameter, where N is an integer. Hyperthreading (using more threads than physical CPUs) usually does not provide a significant speedup, and can be detrimental in some cases. ","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"To directly run a script in parallel, use:","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"julia -t auto example.jl","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"note: Note\nThe number of threads used for computation of the MDDF is the number of physical CPUs of the computer, which are obtained programmatically. Most times the use of hyper-threading is not beneficial. Adjust the number of threads with the Options(nthreads=N) parameter.","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"warning: Warning\nIf the calculations get Killed by no apparent reason, that is probably because you are running out of memory because of the many parallel computations running. One way to alleviate this problem is to force garbage collection, usingoptions = Options(GC=true,GC_threshold=0.5)\nR = mddf(trajectory,options)\nThe GC_threshold=0.5 indicates that if the free memory is smaller than 50% of the total memory of the machine, a garbage-collection run will occur. The default parameters are GC=true and GC_threshold=0.1. ","category":"page"},{"location":"multiple/#Working-with-multiple-trajectories","page":"Multiple trajectories","title":"Working with multiple trajectories","text":"","category":"section"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"Very commonly, one has multiple trajectories of the same system, and we want to obtain the average results of all trajectories. We provide a simple scheme to average the results of multiple MDDF calculations:","category":"page"},{"location":"multiple/#Create-a-vector-of-result-data-structures,-without-initialization","page":"Multiple trajectories","title":"Create a vector of result data structures, without initialization","text":"","category":"section"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"Let us assume that we have three Gromacs trajectories, with file names traj1.xtc, traj2.xtc, traj3.xtc. First let us create a list with these file names:","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"trajectory_files = [ \"traj1.xtc\" , \"traj2.xtc\" , \"traj3.xtc\" ]","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"And define an empty vector of Result structures:","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"results = Result[]","category":"page"},{"location":"multiple/#Run-the-calculations-in-a-loop","page":"Multiple trajectories","title":"Run the calculations in a loop","text":"","category":"section"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"The calculation on the multiple trajectories is then performed in a simple loop, such as","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"atoms = PDBTools.readPDB(\"./system.pdb\")\nsolute = Selection(atoms,\"protein\",nmols=1)\nsolvent = Selection(atoms,\"resname TMAO\",,natomspermol=14)\nfor file in trajectory_files\n trajectory = Trajectory(file,solute,solvent)\n # compute the MDDF data and push the result to the results array\n push!(results, mddf(trajectory))\nend","category":"page"},{"location":"multiple/#Merge-the-results-of-several-trajectories,-with-proper-weights","page":"Multiple trajectories","title":"Merge the results of several trajectories, with proper weights","text":"","category":"section"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"Of course, the resulting results vector will contain at each position the results of each calculation. To merge these results in a single result data structure, use:","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"R = merge(results)","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"The R structure generated contains the averaged results of all calculations, with weights proportional to the number of frames of each trajectory. That is, if the first trajectory had 2000 frames, and the second and third trajectories have 1000 frames each, the first trajectory will have a weight of 0.5 on the final results. The merge function can be used to merge previously merged results with new results as well.","category":"page"},{"location":"multiple/","page":"Multiple trajectories","title":"Multiple trajectories","text":"tip: Tip\nThe names of the files and and weights are stored in the R.files and R.weights vectors of the results structure:julia> R.files\n3-element Array{String,1}:\n \"./traj1.xtc\"\n \"./traj2.xtc\"\n \"./traj3.xtc\"\n\njulia> R.weights\n2-element Array{Float64,1}:\n 0.5\n 0.25\n 0.25\nIt is not a bad idea to check if that is what you were expecting.","category":"page"},{"location":"save/#save","page":"Save and load","title":"Save and load results","text":"","category":"section"},{"location":"save/","page":"Save and load","title":"Save and load","text":"Three functions serve the purpose of saving and loading the results obtained with ComplexMixtures:","category":"page"},{"location":"save/#Save-data-to-recover-it-later","page":"Save and load","title":"Save data to recover it later","text":"","category":"section"},{"location":"save/","page":"Save and load","title":"Save and load","text":"save(results,\"results.json\")","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"where results is the output data structure of the mddf() calculation, and results.json is the output file to be created. The file is written in JSON format, thus is not naturally human-readable.","category":"page"},{"location":"save/#Load-saved-data","page":"Save and load","title":"Load saved data","text":"","category":"section"},{"location":"save/","page":"Save and load","title":"Save and load","text":"results = load(\"results.json\")","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"The load function reads the output of the save function above, and restores the results data structure.","category":"page"},{"location":"save/#Write-data-in-a-human-readable-format","page":"Save and load","title":"Write data in a human-readable format","text":"","category":"section"},{"location":"save/","page":"Save and load","title":"Save and load","text":"If you Want the results to be written as simple ASCII tables such that you can read them with another analysis program, plotting graphic, or just want to inspect the data visually, use:","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"write(results,\"results.dat\")","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"Three files will be created by this function:","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"results.dat: Contains the main results, as the MDDF and KB-integral data.","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"results-ATOM_CONTRIB_SOLVENT.dat: contains the contribution of each atom type of the solvent to the MDDF.","category":"page"},{"location":"save/","page":"Save and load","title":"Save and load","text":"results-ATOM_CONTRIB_SOLUTE.dat: contains the contribution of each atom type of the solute to the MDDF.","category":"page"},{"location":"trajectory/#trajectories","page":"Loading the trajectory","title":"Loading trajectories","text":"","category":"section"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"To initialize a trajectory file for computation, use the command","category":"page"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"trajectory = Trajectory(\"trajectory.xtc\",solute,solvent)","category":"page"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"where solute and solvent are defined with the Selection function described before. This function opens the stream for reading frames, which are read once a time when the coordinates are required for computing the MDDF.","category":"page"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"The Trajectory function uses Chemfiles in background, and thus the most common trajectory formats are supported, as the ones produced with NAMD, Gromacs, LAMMPS, Amber, etc. ","category":"page"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"tip: Tip\nThe format of the trajectory file is automatically determined by Chemfiles from the extension of the file. However, it can be provided by the user with the format keyword, for example:trajectory = Trajectory(\"trajectory.xtc\",solute,solvent,format=\"xtc\")","category":"page"},{"location":"quickguide/#Quick-Guide","page":"Quick Guide","title":"Quick Guide","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Of course, follow the installation instructions first. A complete working example is shown below, and in the section that follows each command is described in detail.","category":"page"},{"location":"quickguide/#Complete-example","page":"Quick Guide","title":"Complete example","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Here we show the input file required for the study of the solvation of a protein by the TMAO solvent, which is a molecule 4 atoms. The protein is assumed to be at infinite dilution in the simulation. The trajectory of the simulation is in DCD format in this example, which is the default output of NAMD and CHARMM simulation packages.","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"# Activate environment (see the Installation -> Recommended Workflow manual section)\nimport Pkg; Pkg.activate(\"/home/user/MyNewPaper\")\n\n# Load packages\nusing PDBTools\nusing ComplexMixtures \nusing Plots\n\n# Load PDB file of the system\natoms = readPDB(\"./system.pdb\")\n\n# Select the protein and the TMAO molecules\nprotein = select(atoms,\"protein\")\ntmao = select(atoms,\"resname TMAO\")\n\n# Setup solute and solvent structures\nsolute = Selection(protein,nmols=1)\nsolvent = Selection(tmao,natomspermol=14)\n\n# Setup the Trajectory structure\ntrajectory = Trajectory(\"./trajectory.dcd\",solute,solvent)\n\n# Run the calculation and get results\nresults = mddf(trajectory)\n\n# Save the results to recover them later if required\nsave(results,\"./results.json\")\n\n# Plot the some of the most important results \nplot(results.d,results.mddf,xlabel=\"d\",ylabel=\"MDDF\") # plot the MDDF\nsavefig(\"./mddf.pdf\")\nplot(results.d,results.kb,xlabel=\"d\",ylabel=\"KB\") # plot the KB \nsavefig(\"./kb.pdf\")","category":"page"},{"location":"quickguide/#Running-the-example","page":"Quick Guide","title":"Running the example","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Given that this code is saved into a file named example.jl, it can be run within the Julia REPL with:","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"julia> include(\"example.jl\")","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"or directly with:","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"julia -t auto example.jl","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"where -t auto will launch julia with multi-threading. It is highly recommended to use multi-threading!","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"note: Note\nJulia compiles the code the first time it is run in each section. Thus, running script from the command line with, for example, julia -t auto example.jl may appear slow, particularly if you are modifying the script interactively. Ideally, do not restart Julia, just repeatedly include your script in the same Julia section. The second time the script is loaded will be much faster. For example:julia> @time include(\"./example.jl\") \n# ... some output\n27.554095 seconds (72.13 M allocations: 4.623 GiB, 4.37% gc time, 11.96% compilation time)\njulia> @time include(\"./example.jl\")\n# ... some output\n0.703780 seconds (3.24 M allocations: 897.260 MiB, 12.22% gc time)The first time the script was called it took ~30s, which included compilation of the code and loading of the packages. The second time the script was included it took 0.7s. Thus, for interactive modification of the script, don't restart Julia.This has been much improved in Julia 1.9, particularly if a stable environment is used, as suggested.","category":"page"},{"location":"quickguide/#Detailed-description-of-the-example","page":"Quick Guide","title":"Detailed description of the example","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Start julia and load the ComplexMixtures package, using:","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"using ComplexMixtures","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"And here we will use the PDBTools package to obtain the selections of the solute and solvent molecules: ","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"using PDBTools","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"(see Set solute and solvent for details).","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"The fastest way to understand how to use this package is through an example. ","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Let us consider a system of three components: a protein, water, a cossolvent: TMAO (trimetylamine-N-oxyde), which is a common osmolyte known to stabilize protein structures. A picture of this system is shown below, with the protein in blue, water, and TMAO molecules. The system was constructed with Packmol and the figure was produced with VMD.","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"![](\"../figures/proteinTMAO.png\")
\n![](\"../figures/coordination.png\")
\n![](\"../figures/density.png\")
\n![](\"../figures/density3D_final.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Protein_in_Glycerol/Data/system.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Protein_in_Glycerol/MDDF/mddf.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Protein_in_Glycerol/MDDF/mddf_atom_contrib.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Protein_in_Glycerol/Density2D/density2D.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Protein_in_Glycerol/Density3D/density3D_final.png\")
\n![](\"https://github.com/m3g/ComplexMixturesExamples/raw/main/Polyacrylamide_in_DMF/results/mddf_groups.png\")
\n![](\"./figures/KBs.png\")
\n![](\"./figures/Gamma.png\")
\n
+
+
+