m3g / complexmixtures.jl

Package to perform minimum-distance distribution analyses of complex solute-solvent interactions

ComplexMixtures.jl

A package to study the structure of solutions formed by solutes and solvents of complex molecular shapes.

Documentation:

The documentation is available at: https://m3g.github.io/ComplexMixtures.jl

Examples

A series of examples of applications can be found at: https://m3g.github.io/ComplexMixtures.jl/stable/examples

Overview

ComplexMixtures is a package to study the solute and solvent interactions of mixtures of molecules of complex shape. Conventional radial distribution functions are not appropriate to represent the structure of a solvent around a solute with many atoms, and a variable, non-spherical shape.

Typical solutes of complex shape are proteins, nucleic acids, and polymers in general. Smaller molecules like lipids, carbohydrates, etc, are also complex enough such that representing the structure of the solution of those molecules with distribution functions is not trivial.

Minimum-Distance Distribution Functions (MDDFs) are a very general and practical way to represent solute-solvent interactions for molecules with arbitrarily complex sizes and geometries. Briefly, instead of computing the density distribution function of a particular atom or the center-of-mass of the molecules, one computes the distribution function of the minimum-distance between any solute and solvent atoms. This provides a size and shape-independent distribution which is very natural to interpret in terms of molecular interactions.

Minimum-distance distribution function and its decomposition into molecular groups.

Additionally, the MDDFs can be decomposed into contributions of each type of atom (or groups of atoms) of the solute and solvent molecules, such that the profiles of the distributions can be interpreted in terms of the chemical nature of the species involved in the interactions at each distance.

Finally, as with radial distribution functions, MDDFs can be used to compute Kirkwood-Buff integrals to connect the accumulation or depletion of the solvents components to thermodynamic properties, like protein structural stability, solubility, and others.

Density map of a solvent in the vicinity of each protein residue.

References

If this package was useful to you, please cite the following articles:

• L. Martínez, ComplexMixtures.jl: Investigating the structure of solutions of complex-shaped molecules from a solvent-shell perspective. J. Mol. Liq. 347, 117945, 2022. [Full Text]

• L. Martínez, S. Shimizu, Molecular interpretation of preferential interactions in protein solvation: a solvent-shell perspective by means of minimum-distance distribution functions. J. Chem. Theor. Comp. 13, 6358–6372, 2017. [Full Text]

Additional resources

Please go to http://m3g.iqm.unicamp.br to find additional resources and publications associated with this project.

complexmixtures.jl's Issues

document coordination_number_only option

there is no documentation for the option in the mddf function.

TagBot trigger issue

This issue is used to trigger TagBot; feel free to unsubscribe.

If you haven't already, you should update your TagBot.yml to include issue comment triggers.
Please see this post on Discourse for instructions and more details.

Error when cutoff option enabled

Hi,
I get the following error when running the mddf function with usecutoff=true option:

ERROR: LoadError: TaskFailedException

    nested task error: type MinimumDistance has no field dmin_mol
    Stacktrace:
     [1] getproperty
       @ ./Base.jl:37 [inlined]
     [2] inbulk
       @ ~/.julia/packages/ComplexMixtures/Jm0qC/src/mddf.jl:55 [inlined]
     [3] mddf_frame!(R::Result, system::CellListMap.PeriodicSystems.PeriodicSystem2{:list, Vector{StaticArraysCore.SVector{3, Float64}}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}, buff::ComplexMixtures.Buffer, options::Options, frame_weight::Float64, RNG::RandomNumbers.Xorshifts.Xoroshiro128Plus)
       @ ComplexMixtures ~/.julia/packages/ComplexMixtures/Jm0qC/src/mddf.jl:296
     [4] macro expansion
       @ ~/.julia/packages/ComplexMixtures/Jm0qC/src/mddf.jl:212 [inlined]
     [5] (::ComplexMixtures.var"#138#threadsfor_fun#83"{ComplexMixtures.var"#138#threadsfor_fun#78#84"{Bool, ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, StepRange{Int64, Int64}, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, Vector{StaticArraysCore.SVector{3, Float64}}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result}, Result, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Enumerate{ChunkSplitters.Chunk{UnitRange{Int64}, ChunkSplitters.FixedCount}}}})(tid::Int64; onethread::Bool)
       @ ComplexMixtures ./threadingconstructs.jl:163
     [6] #138#threadsfor_fun
       @ ./threadingconstructs.jl:130 [inlined]
     [7] (::Base.Threads.var"#1#2"{ComplexMixtures.var"#138#threadsfor_fun#83"{ComplexMixtures.var"#138#threadsfor_fun#78#84"{Bool, ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, StepRange{Int64, Int64}, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, Vector{StaticArraysCore.SVector{3, Float64}}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result}, Result, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Enumerate{ChunkSplitters.Chunk{UnitRange{Int64}, ChunkSplitters.FixedCount}}}}, Int64})()
       @ Base.Threads ./threadingconstructs.jl:108
Stacktrace:
 [1] threading_run(fun::ComplexMixtures.var"#138#threadsfor_fun#83"{ComplexMixtures.var"#138#threadsfor_fun#78#84"{Bool, ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, StepRange{Int64, Int64}, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, Vector{StaticArraysCore.SVector{3, Float64}}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result}, Result, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Enumerate{ChunkSplitters.Chunk{UnitRange{Int64}, ChunkSplitters.FixedCount}}}}, static::Bool)
   @ Base.Threads ./threadingconstructs.jl:120
 [2] macro expansion
   @ ./threadingconstructs.jl:168 [inlined]
 [3] mddf(trajectory::ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, options::Options; frame_weights::Vector{Float64}, coordination_number_only::Bool)
   @ ComplexMixtures ~/.julia/packages/ComplexMixtures/Jm0qC/src/mddf.jl:168
 [4] mddf
   @ ~/.julia/packages/ComplexMixtures/Jm0qC/src/mddf.jl:117 [inlined]
 [5] myfunction()
   @ Main ~/Desktop/work/mddf.jl:38
 [6] top-level scope
   @ ~/Desktop/work/mddf.jl:111

check indices of custom groups relative to atsel.indices array

This test is useful for preventing the user to define groups that contain atoms that do not belong to solute or solvent selection. For example, this would error:

atsel = AtomSelection(
    water,
    group_atom_indices = [ findall(Select("name CA")) ]
)

because water has no CA atom.

mddf exits with Bounds Error

I have successfully computed the mddf for a multi-component system, a protein, alcohols, salts and water. Computing mddf between protein and any other solute or the solvent work well. Computing the mddf between the alcohols additionally works well, however, when I attempt to compute the mddf between the alcohols and water:
using PDBTools using ComplexMixtures atoms = readPDB("./1/production.pdb") alc = select(atoms,"resname alc") wat = select(atoms, "resname SOL and not name MW4") solute = Selection(alc, nmols=55) solvent = Selection(wat, natomspermol=3) traj = Trajectory("./1/production.xtc", solute, solvent, format="XTC") options = Options(cutoff=20, dbulk=32.5, nthreads=16) results = mddf(traj, options)

I receive the following Exception:

`Starting MDDF calculation in parallel:
21126 frames will be considered.
Number of calculation threads: 16
Solute: 1210 atoms belonging to 55 molecules.
Solvent: 39738 atoms belonging to 13246 molecules.
Progress: 95%|███████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████▊ | ETA: 0:00:50ERROR: TaskFailedException
Stacktrace:
[1] wait
@ ./task.jl:345 [inlined]
[2] threading_run(fun::ComplexMixtures.var"#99#threadsfor_fun#80"{ComplexMixtures.var"#99#threadsfor_fun#75#81"{ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, StaticArraysCore.SVector{3, Float64}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result{Matrix{Float64}}}, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Chunk{UnitRange{Int64}}}}, static::Bool)
@ Base.Threads ./threadingconstructs.jl:38
[3] macro expansion
@ ./threadingconstructs.jl:89 [inlined]
[4] mddf(trajectory::ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, options::Options)
@ ComplexMixtures ~/.julia/packages/ComplexMixtures/61WXz/src/mddf.jl:153
[5] top-level scope
@ REPL[15]:1

nested task error: BoundsError: attempt to access 1625-element Vector{Float64} at index [1626]
Stacktrace:
 [1] getindex
   @ ./array.jl:924 [inlined]
 [2] updatecounters!(R::Result{Matrix{Float64}}, system::CellListMap.PeriodicSystems.PeriodicSystem2{:list, StaticArraysCore.SVector{3, Float64}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}})
   @ ComplexMixtures ~/.julia/packages/ComplexMixtures/61WXz/src/updatecounters.jl:28
 [3] mddf_frame!(R::Result{Matrix{Float64}}, system::CellListMap.PeriodicSystems.PeriodicSystem2{:list, StaticArraysCore.SVector{3, Float64}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}, buff::ComplexMixtures.Buffer, options::Options, RNG::RandomNumbers.Xorshifts.Xoroshiro128Plus)
   @ ComplexMixtures ~/.julia/packages/ComplexMixtures/61WXz/src/mddf.jl:247
 [4] macro expansion
   @ ~/.julia/packages/ComplexMixtures/61WXz/src/mddf.jl:181 [inlined]
 [5] (::ComplexMixtures.var"#99#threadsfor_fun#80"{ComplexMixtures.var"#99#threadsfor_fun#75#81"{ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, StaticArraysCore.SVector{3, Float64}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result{Matrix{Float64}}}, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Chunk{UnitRange{Int64}}}})(tid::Int64; onethread::Bool)
   @ ComplexMixtures ./threadingconstructs.jl:84
 [6] #99#threadsfor_fun
   @ ./threadingconstructs.jl:51 [inlined]
 [7] (::Base.Threads.var"#1#2"{ComplexMixtures.var"#99#threadsfor_fun#80"{ComplexMixtures.var"#99#threadsfor_fun#75#81"{ComplexMixtures.ChemFile{StaticArraysCore.SVector{3, Float64}}, Options, ReentrantLock, Vector{ComplexMixtures.Buffer}, Vector{CellListMap.PeriodicSystems.PeriodicSystem2{:list, StaticArraysCore.SVector{3, Float64}, Vector{ComplexMixtures.MinimumDistance}, CellListMap.Box{CellListMap.OrthorhombicCell, 3, Float64, Float64, 9, Float64}, CellListMap.CellListPair{Vector{StaticArraysCore.SVector{3, Float64}}, 3, Float64, CellListMap.NotSwapped}, CellListMap.AuxThreaded{3, Float64}}}, Vector{Result{Matrix{Float64}}}, RandomNumbers.Xorshifts.Xoroshiro128Plus, ChunkSplitters.Chunk{UnitRange{Int64}}}}, Int64})()
   @ Base.Threads ./threadingconstructs.jl:30

`
I gather that the Vector element is 1625 in length from the cutoff and the bin width but haven't a clue why the method is addressing an index beyond the Vector length. Any help is greatly appreciated.

normalization warning is printed even if coordination_number_only = true

Also, the output could/should inform that the coordination number only was computed.

julia> r = mddf(trajectory, options; coordination_number_only = true)
 
--------------------------------------------------------------------------------
Starting MDDF calculation in parallel:
51 frames will be considered.
Number of calculation threads: 20
Solute: 151572 atoms belonging to 1 molecule.
Solvent: 442324 atoms belonging to 110581 molecules.
Progress: 100%|███████████████████████████████████████████████████████████████████████████████| Time: 0:00:31
┌ Warning: Ideal-gas histogram bins with zero samples. 
│ Increase n_random_samples and/or number of trajectory frames.
└ @ ComplexMixtures
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
MDDF Overview - ComplexMixtures - Version 2.0.0
--------------------------------------------------------------------------------

Solvent properties:
-------------------

Simulation concentration: 1.0857352013753405 mol L⁻¹
Molar volume: 921.0348883717351 cm³ mol⁻¹

Concentration in bulk: 0.9568297861113825 mol L⁻¹
Molar volume in bulk: 1045.11796613697 cm³ mol⁻¹

Solute properties:
------------------

Simulation Concentration: 9.81846068832205e-6 mol L⁻¹
Estimated solute partial molar volume: -1.3721230822357437e7 cm³ mol⁻¹

Using dbulk = 8.0Å:
Molar volume of the solute domain: 0.0 cm³ mol⁻¹

Auto-correlation: false

Trajectory files and weights:

   ../ZIKV_EM_memb_631_cg_frames_vlp_solvent_pbc_mol_skip-5.gro - w = 1.0

Long range MDDF mean (expected 1.0): 0.0 ± 0.0
Long range RDF mean (expected 1.0): 0.0 ± 0.0

--------------------------------------------------------------------------------