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 = AtomSelection(protein,nmols=1)
+solvent = AtomSelection(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 contributions can be retrieved using the contributions function, with the SoluteGroup and SolventGroup selectors.
For example, if the MDDF of water (solvent) relative to a solute was computed, and water has atom names OH2, H1, H2, one can retrieve the contributions of the oxygen atom with:
OH2 = contributions(results, SolventGroup(["OH2"]))or with, if OH2 is the first atom in the molecule,
OH2 = contributions(results, SolventGroup([1]))The contributions of the hydrogen atoms can be obtained, similarly, with:
H = contributions(results, SolventGroup(["H1", "H2"]))or with, if OH2 is the first atom in the molecule,
H = contributions(results, SolventGroup([2, 3]))Each of these calls will return a vector of the constributions of these atoms to the total MDDF.
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, contributions(results, SolventGroup(["OH2"])), label=["OH2"], linewidth=2)
+plot!(xlabel="Distance / Å", ylabel="MDDF")
Using PDBTools
If the solute is a protein, or other complex molecule, selections defined with PDBTools can be used. For example, this will retrieve the contribution of the acidic residues of a protein to total MDDF:
using PDBTools
+atoms = readPDB("system.pdb")
+acidic_residues = select(atoms, "acidic")
+acidic_contributions = contributions(results, SoluteGroup(acidic_residues))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.
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(results, SoluteGroup(charged_residues))
+
+neutral_residues = PDBTools.select(atoms,"neutral")
+neutral_contributions = contributions(atoms, SoluteGroup(neutral_residues))The charged_contributions and neutral_contributions 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.
Reference functions
ComplexMixtures.contributions — Methodcontributions(R::Result, group::Union{SoluteGroup,SolventGroup}; type = :mddf)Returns the contributions of the atoms of the solute or solvent to the MDDF, coordiantion number or MD count.
Arguments
R::Result: The result of a calculation.group::Union{SoluteGroup,SolventGroup}: The group of atoms to consider.type::Symbol: The type of contributions to return. Can be:mddf(default),:coordination_numberor:md_count.
Examples
julia> using ComplexMixtures, PDBTools
+
+julia> dir = ComplexMixtures.Testing.data_dir*"/Gromacs";
+
+julia> atoms = readPDB(dir*"/system.pdb");
+
+julia> protein = select(atoms, "protein");
+
+julia> emim = select(atoms, "resname EMI");
+
+julia> solute = AtomSelection(protein, nmols = 1)
+AtomSelection
+ 1231 atoms belonging to 1 molecule(s).
+ Atoms per molecule: 1231
+ Number of groups: 1231
+
+julia> solvent = AtomSelection(emim, natomspermol = 20)
+AtomSelection
+ 5080 atoms belonging to 254 molecule(s).
+ Atoms per molecule: 20
+ Number of groups: 20
+
+julia> results = load(dir*"/protein_EMI.json"); # load pre-calculated results
+
+julia> contributions(results, SoluteGroup(["CA", "CB"])) # contribution of CA and CB atoms to the MDDF
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+![](\"../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 AtomSelection Contains the number of atoms, number of atoms per molecule and number of molecules of the solute.\nsolvent Properties of the solvent. AtomSelection 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":"results/#Reference-functions","page":"Results","title":"Reference functions","text":"","category":"section"},{"location":"results/","page":"Results","title":"Results","text":"Modules = [ComplexMixtures]\nPages = [\"results.jl\"]","category":"page"},{"location":"results/#ComplexMixtures.Density","page":"Results","title":"ComplexMixtures.Density","text":"mutable struct Density\n\nStructure to contain the density values obtained from the calculation.\n\nsolute::Float64\nsolvent::Float64\nsolvent_bulk::Float64\n\n\n\n\n\n","category":"type"},{"location":"results/#ComplexMixtures.Result","page":"Results","title":"ComplexMixtures.Result","text":"mutable struct Result\n\nStructure to contain the results of the MDDF calculation.\n\nVersion::VersionNumber\nnbins::Int64\ndbulk::Float64\ncutoff::Float64\nd::Vector{Float64}\nmd_count::Vector{Float64}\nmd_count_random::Vector{Float64}\ncoordination_number::Vector{Float64}\ncoordination_number_random::Vector{Float64}\nmddf::Vector{Float64}\nkb::Vector{Float64}\nautocorrelation::Bool\nsolute::AtomSelection\nsolvent::AtomSelection\nsolute_group_count::Vector{Vector{Float64}}\nsolvent_group_count::Vector{Vector{Float64}}\nrdf_count::Vector{Float64}\nrdf_count_random::Vector{Float64}\nsum_rdf_count::Vector{Float64}\nsum_rdf_count_random::Vector{Float64}\nrdf::Vector{Float64}\nkb_rdf::Vector{Float64}\ndensity::ComplexMixtures.Density\nvolume::ComplexMixtures.Volume\nfiles::Vector{ComplexMixtures.TrajectoryFileOptions}\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":"results/#Base.merge-Tuple{Vector{<:Result}}","page":"Results","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":"results/#ComplexMixtures.load-Tuple{String}","page":"Results","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":"results/#ComplexMixtures.overview-Tuple{Result}","page":"Results","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":"results/#ComplexMixtures.save-Tuple{Result, String}","page":"Results","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":"example1/#Protein-in-water/glycerol","page":"◦ Protein in water/glycerol","title":"Protein in water/glycerol","text":"","category":"section"},{"location":"example1/","page":"◦ Protein in water/glycerol","title":"◦ Protein in water/glycerol","text":"The following examples consider a system composed a protein solvated by a mixture of water and glycerol, built with Packmol. The simulations were performed with NAMD with periodic boundary conditions and a NPT ensemble at room temperature and pressure. Molecular pictures were produced with VMD and plots were produced with Julia's Plots library.","category":"page"},{"location":"example1/","page":"◦ Protein in water/glycerol","title":"◦ Protein in water/glycerol","text":"![](\"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![](\"../figures/oh2.png\")
","category":"page"},{"location":"contrib/#Using-PDBTools","page":"Atomic and group contributions","title":"Using PDBTools","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"If the solute is a protein, or other complex molecule, selections defined with PDBTools can be used. For example, this will retrieve the contribution of the acidic residues of a protein to total MDDF:","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"using PDBTools\natoms = readPDB(\"system.pdb\")\nacidic_residues = select(atoms, \"acidic\")\nacidic_contributions = contributions(results, SoluteGroup(acidic_residues))","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":"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(results, SoluteGroup(charged_residues))\n\nneutral_residues = PDBTools.select(atoms,\"neutral\")\nneutral_contributions = contributions(atoms, SoluteGroup(neutral_residues))","category":"page"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"The charged_contributions and neutral_contributions 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":"contrib/#Reference-functions","page":"Atomic and group contributions","title":"Reference functions","text":"","category":"section"},{"location":"contrib/","page":"Atomic and group contributions","title":"Atomic and group contributions","text":"Modules = [ComplexMixtures]\nPages = [\"contributions.jl\"]","category":"page"},{"location":"contrib/#ComplexMixtures.contributions-Tuple{Result, Union{SoluteGroup, SolventGroup}}","page":"Atomic and group contributions","title":"ComplexMixtures.contributions","text":"contributions(R::Result, group::Union{SoluteGroup,SolventGroup}; type = :mddf)\n\nReturns the contributions of the atoms of the solute or solvent to the MDDF, coordiantion number or MD count.\n\nArguments\n\nR::Result: The result of a calculation.\ngroup::Union{SoluteGroup,SolventGroup}: The group of atoms to consider.\ntype::Symbol: The type of contributions to return. Can be :mddf (default), :coordination_number or :md_count.\n\nExamples\n\njulia> using ComplexMixtures, PDBTools\n\njulia> dir = ComplexMixtures.Testing.data_dir*\"/Gromacs\";\n\njulia> atoms = readPDB(dir*\"/system.pdb\");\n\njulia> protein = select(atoms, \"protein\");\n\njulia> emim = select(atoms, \"resname EMI\"); \n\njulia> solute = AtomSelection(protein, nmols = 1)\nAtomSelection \n 1231 atoms belonging to 1 molecule(s).\n Atoms per molecule: 1231\n Number of groups: 1231\n\njulia> solvent = AtomSelection(emim, natomspermol = 20)\nAtomSelection \n 5080 atoms belonging to 254 molecule(s).\n Atoms per molecule: 20\n Number of groups: 20\n\njulia> results = load(dir*\"/protein_EMI.json\"); # load pre-calculated results\n\njulia> contributions(results, SoluteGroup([\"CA\", \"CB\"])) # contribution of CA and CB atoms to the MDDF\n\n\n\n\n\n\n","category":"method"},{"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 N option, where N is the number of processes to be used. For example, to use 8 parallel processes, use:","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"julia -t 8 example.jl","category":"page"},{"location":"parallel/","page":"Parallel execution","title":"Parallel execution","text":"The computation will use a number of parallel processes equal to N. Use -t auto to automatically pick the number of threads available in your computer. ","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 threads available to Julia. Many computers allow hyperthreading, and not necessarily this this beneficial for the execution of this package. The optimal number of threads may vary.Independently of the number of threads initialized with the -t command-line parameter, the number of processes launched by ComplexMixtures in any given computation can be adjusted by the Options(nthreads=N) option. This won't provide any speedup if the optional number of threads is greater than the number of threads available to Julia at runtime.","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.3. Read the predefinition of atom groups section if you are experiencing memory issues.","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 = AtomSelection(atoms,\"protein\",nmols=1)\nsolvent = AtomSelection(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":"save/","page":"Save and load","title":"Save and load","text":"Modules = [ComplexMixtures]\nPages = [\"tools/write.jl\"]","category":"page"},{"location":"save/#Base.write-Tuple{Result, String}","page":"Save and load","title":"Base.write","text":"write(\n R::Result, filename::String;\n solute_group_names::Vector{String} = R.solute.group_names,\n solvent_group_names::Vector{String} = R.solvent.group_names,\n)\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 group names are defined in R, the solute_group_names and solvent_group_names arguments are not necessary. If they are not defined, the user can pass the names of the groups as strings in the solute_group_names and solvent_group_names arguments.\n\n\n\n\n\n","category":"method"},{"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 AtomSelection 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":"trajectory/#Reference-functions","page":"Loading the trajectory","title":"Reference functions","text":"","category":"section"},{"location":"trajectory/","page":"Loading the trajectory","title":"Loading the trajectory","text":"Modules = [ComplexMixtures]\nPages = [\"Trajectory.jl\"]","category":"page"},{"location":"trajectory/#ComplexMixtures.Trajectory","page":"Loading the trajectory","title":"ComplexMixtures.Trajectory","text":"Trajectory(filename::String, solute::AtomSelection, solvent::AtomSelection; 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":"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/#Basic-example","page":"Quick Guide","title":"Basic 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/#Input-files","page":"Quick Guide","title":"Input files","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"The files necessary to run this would be:","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"system.pdb: a PDB file of the complete simulated system.\ntrajectory.dcd: the simulation trajectory, here exemplified in the DCD format.\nscript.jl: the Julia script, described below.","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"These files are not provided for this example. For complete running examples, please check our examples section.","category":"page"},{"location":"quickguide/#The-Julia-script","page":"Quick Guide","title":"The Julia script","text":"","category":"section"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"using Markdown\ncode = Markdown.parse(\"\"\"\n\\`\\`\\`julia\n$(read(\"./assets/scripts/basic/script.jl\", String))\n\\`\\`\\`\n\"\"\")","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"Given that this code is saved into a file named script.jl, it can be run within the Julia REPL with:","category":"page"},{"location":"quickguide/","page":"Quick Guide","title":"Quick Guide","text":"julia> include(\"script.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 script.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\nSome newer CPUs have \"fast\" and \"slow\" cores, designed for performance or energy savings. Thus using all cores, with -t auto, may not be the best strategy for optimal performance. Experimenting with different number of cores using -t N where N is the number of cores used is always necessary for tunning performance.","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 cosolvent: 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![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/Glycerol_in_Water/system.png\")
\n![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/Polyacrylamide_in_DMF/system.png\")
\n![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/Polyacrylamide_in_DMF/simulation/dmf.png\")
![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/Polyacrylamide_in_DMF/simulation/polyacrylamide.png\")
![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/Polyacrylamide_in_DMF/results/map2D_acr.png\")
\n![](\"https://raw.githubusercontent.com/m3g/ComplexMixturesExamples/main/POPC_in_Water-Ethanol/system.png\")
\n![](\"../figures/coordination.png\")
\n![](\"../figures/density.png\")
\n![](\"../figures/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
+
+
+