Merge pull request #49 from m3g/new_call_without_Trajectory

New call without trajectory

.github/workflows/ci.yml

@@ -54,12 +54,6 @@ jobs:
             using Pkg
             Pkg.develop(PackageSpec(path=pwd()))
             Pkg.instantiate()'
-      - run: |
-          julia --project=docs -e '
-            import Pkg; Pkg.add("Documenter")
-            using Documenter: doctest
-            using ComplexMixtures
-            doctest(ComplexMixtures)'
       - run: julia --project=docs docs/make.jl
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Project.toml

@@ -1,7 +1,7 @@
 name = "ComplexMixtures"
 uuid = "6f35c628-ac57-5bae-8ea9-703a8964f6e9"
 authors = ["Leandro Martinez <lmartine@unicamp.br>"]
-version = "2.8.6-DEV"
+version = "2.9.0-DEV"
 
 [deps]
 CellListMap = "69e1c6dd-3888-40e6-b3c8-31ac5f578864"

docs/src/assets/scripts/basic/script.jl

@@ -20,14 +20,9 @@ tmao = select(atoms, "resname TMAO")
 solute = AtomSelection(protein, nmols=1)
 solvent = AtomSelection(tmao, natomspermol=14)
 
-# Setup the Trajectory structure: this will define which
-# coordinates are used to compute the MDDF when reading
-# the trajectory file.
-trajectory = Trajectory("./trajectory.dcd", solute, solvent)
-
-# Run the calculation and get results: this is the computationally
-# intensive part of the calculation.
-results = mddf(trajectory, Options(bulk_range=(8.0, 12.0)))
+# Run the calculation over the trajectory.dcd file and get results: 
+# this is the computationally intensive part of the calculation.
+results = mddf("./trajectory.dcd", solute, solvent, Options(bulk_range=(8.0, 12.0)))
 
 # Save the results to recover them later if required
 save(results, "./results.json")

docs/src/assets/scripts/example1/script1.jl

@@ -31,8 +31,7 @@ solvent = AtomSelection(glyc, natomspermol=14)
 trajectory_file = "./glyc50_traj.dcd"
 
 # Run mddf calculation, and save results
-trajectory = Trajectory(trajectory_file, solute, solvent)
-results = mddf(trajectory, Options(bulk_range=(10.0, 15.0)))
+results = mddf(trajectory_file, solute, solvent, Options(bulk_range=(10.0, 15.0)))
 save(results, "glyc50_results.json")
 println("Results saved to glyc50_results.json")
 

docs/src/assets/scripts/example2/script1.jl

@@ -24,14 +24,11 @@ acr = select(system, "resname FACR or resname ACR or resname LACR")
 solute = AtomSelection(acr, nmols=1)
 solvent = AtomSelection(dmf, natomspermol=12)
 
-# Set the trajectory structure
-trajectory = Trajectory(trajectory_file, solute, solvent)
-
 # Use a large dbulk distance for better KB convergence
 options = Options(bulk_range=(20.0, 25.0))
 
 # Compute the mddf and associated properties
-results = mddf(trajectory, options)
+results = mddf(trajectory_file, solute, solvent, options)
 
 # Save results to file for later use
 save(results, "./mddf.json")

docs/src/assets/scripts/example3/script1.jl

@@ -26,25 +26,21 @@ solute = AtomSelection(popc, nmols=1)
 # Compute water-POPC distribution and KB integral 
 solvent = AtomSelection(water, natomspermol=3)
 
-# Set the trajectory structure
-trajectory = Trajectory(trajectory_file, solute, solvent)
-
 # We want to get reasonably converged KB integrals, which usually
 # require large solute domains. Distribution functions converge 
 # rapidly (~10Angs or less), on the other side.
 options = Options(bulk_range=(15.0, 20.0))
 
 # Compute the mddf and associated properties
-mddf_water_POPC = mddf(trajectory, options)
+mddf_water_POPC = mddf(trajectory_file, solute, solvent, options)
 
 # Save results to file for later use
 save(mddf_water_POPC, "./mddf_water_POPC.json")
 println("Results saved to ./mddf_water_POPC.json file")
 
 # Compute ethanol-POPC distribution and KB integral 
 solvent = AtomSelection(ethanol, natomspermol=9)
-traj = Trajectory(trajectory_file, solute, solvent)
-mddf_ethanol_POPC = mddf(traj, options)
+mddf_ethanol_POPC = mddf(trajectory_file, solute, solvent, options)
 
 # Save results for later use
 save(mddf_ethanol_POPC, "./mddf_ethanol_POPC.json")

docs/src/assets/scripts/example4/script1.jl

@@ -18,22 +18,21 @@ trajectory_file = "./traj_Glyc.dcd"
 glyc = select(system, "resname GLLM")
 water = select(system, "water")
 
-# Compute Glycerol-Glycerol auto correlation mddf 
-solute = AtomSelection(glyc, natomspermol=14)
-trajectory = Trajectory(trajectory_file, solute) # solute and solvent are the same
+# Compute Glycerol-Glycerol auto correlation mddf: first we initialize the 
+# AtomSelection object, informing the number of atoms per molecule of Glycerol
+glyc_selection = AtomSelection(glyc, natomspermol=14)
 
 # We define a large solute domain (large dbulk) to obtain a good convergence
 # for the KB integral. The mddf converges at much shorter distances.   
 options = Options(bulk_range=(20.0, 25.0))
-mddf_glyc = mddf(trajectory, options)
+mddf_glyc = mddf(trajectory_file, glyc_selection, options)
 
 # Save results for later analysis
 save(mddf_glyc, "./mddf_glyc.json")
 
-# Compute water-glycerol mddf
+# Compute water-glycerol mddf: glyc_selection is the solute, and water is the solvent
 solvent = AtomSelection(water, natomspermol=3)
-trajectory = Trajectory(trajectory_file, solute, solvent)
-mddf_glyc_water = mddf(trajectory, options)
+mddf_glyc_water = mddf(trajectory_file, glyc_selection, solvent, options)
 
 # Save results for later analysis
 save(mddf_glyc_water, "./mddf_glyc_water.json")

docs/src/contributions.md

@@ -18,7 +18,7 @@ using:
 
 ```julia
 using PDBTools, ComplexMixtures
-atoms = readPDB("system.pdb")
+atoms = read_pdb("system.pdb")
 protein = select(atoms,"protein")
 water = select(atoms,"water")
 solute = AtomSelection(protein,nmols=1)
@@ -27,8 +27,7 @@ solvent = AtomSelection(water,natomspermol=3)
 
 The MDDF calculation is executed with:
 ```julia
-trajectory = Trajectory("trajectory.dcd",solute,solvent)
-results = mddf(trajectory, Options(bulk_range=(8.0, 12.0)))
+results = mddf("trajectory.dcd", solute, solvent, Options(bulk_range=(8.0, 12.0)))
 ```
 
 ## Atomic contributions in the result data structure
@@ -94,7 +93,7 @@ with `PDBTools` can be used. For example, this will retrieve the contribution
 of the acidic residues of a protein to total MDDF:
 ```julia
 using PDBTools
-atoms = readPDB("system.pdb")
+atoms = read_pdb("system.pdb")
 acidic_residues = select(atoms, "acidic")
 acidic_contributions = contributions(results, SoluteGroup(acidic_residues))
 ```

docs/src/example1.md

@@ -87,7 +87,7 @@ and the same distribution function, decomposed into the contributions of the hyd
     To change the options of the calculation, set the `Options` structure accordingly and pass it as a parameter to `mddf`. For example:
     ```julia
     options = Options(bulk_range=(10.0, 15.0), stride=5)
-    mddf(trajectory, options)
+    mddf(trajectory_file, solute, solvent, options)
     ```
     The complete set of options available is described [here](@ref options).
 

docs/src/mddf.md

@@ -15,7 +15,7 @@ mddf
 The `mddf` functions is run with, for example:
 
 ```julia
-results = mddf(trajectory, Options(bulk_range=(10.0, 15.0)))  
+results = mddf(trajectory_file, solute, solvent, Options(bulk_range=(10.0, 15.0)))  
 ```
 
 The MDDF along with other results, like the corresponding KB integrals,
@@ -33,7 +33,7 @@ considered. Adjust stride with:
 
 ```julia
 options = Options(stride=5, bulk_range=(10.0, 15.0))
-results = mddf(trajectory, options)
+results = mddf(trajectory_file, solute, solvent, options)
 ```
 
 !!! note
@@ -60,17 +60,27 @@ to set.
 
 ## Coordination numbers only
 
+The coordination number is the unnormalized count of how many molecules of the solvent
+are within a given distance to the solute. Coordination numbers can be computed 
+for systems where the normalization of the distribution functions is not possible
+(or needed) because of an ill definition of an ideal-gas state. For example, 
+in highly heterogeneous systems, on in systems with only a few molecules of the 
+"solvent", the density of the bulk solution might not be properly defined.   
+
+In these cases, nevertheless, coordination numbers can be computed and still 
+provide valuable information about the molecular structure of the system. Coordination
+number can be computed also from the results obtained from a `mddf` run, as explained in 
+the [corresponding section of the Tools menu](@ref coordination_number).
+
 The `coordination_number` function, called with the same arguments as the `mddf`
 function, can be used to compute coordination numbers without the normalization
-required for the MDDF:
+required for the MDDF, providing (possibly much) faster computations when the 
+normalization is not possible or required:
 
 ```@docs
-coordination_number(::Trajectory, ::Options)
+coordination_number(::String)
 ```
 
-This function can be useful if the normalization is not possible or meaningful.
-The computation is much faster if the normalization is not necessary.
-
 !!! note 
-    The `mddf`, `kb`, and random count parameters will be empty when using 
+    The `mddf`, `kb`, and random count parameters will be filled with zeros when using 
     this options, and are meaningless. 

docs/src/multiple.md

@@ -26,14 +26,13 @@ The calculation on the multiple trajectories is then performed in a
 simple loop, such as
 
 ```julia
-atoms = PDBTools.readPDB("./system.pdb")
+atoms = PDBTools.read_pdb("./system.pdb")
 solute = AtomSelection(atoms,"protein",nmols=1)
 solvent = AtomSelection(atoms,"resname TMAO",natomspermol=14)
 options = Options(bulk_range=(8.0, 12.0))
 for file in trajectory_files
-    trajectory = Trajectory(file,solute,solvent)
     # compute the MDDF data and push the result to the results array
-    push!(results, mddf(trajectory, options))
+    push!(results, mddf(trajectory_file, solute, solvent, options))
 end
 ```
 

docs/src/options.md

@@ -6,7 +6,7 @@ to obtain the MDDF. These options can be defined by the user and passed to the
 
 ```julia
 options = Options(lastframe=1000, bulk_range=(8.0, 12.0))
-results = mddf(trajectory, options)
+results = mddf(trajectory_file, solute, solvent, options)
 ```
 
 ## Frame ranges and histogram properties
@@ -108,7 +108,7 @@ optional parameter `frame_weights`.
 
 For example:
 ```julia-repl
-julia> results = mddf(trajectory, options; frame_weights=[0.0, 1.0, 2.0])
+julia> results = mddf(trajectory_file, solute, solvent, options; frame_weights=[0.0, 1.0, 2.0])
 ```
 The code above will assign a larger weight to the third frame of the trajectory.
 These weights are relative (meaning that `[0.0, 1.0, 2.0]` would produce 
@@ -134,7 +134,7 @@ number may still be an interesting information to be retrieved from the
 simulations. To run the computation to compute coordination numbers only, do:
 
 ```julia-repl
-julia> results = mddf(trajectory, options; coordination_number_only = true)
+julia> results = mddf(trajectory_file, solute, solvent, options; coordination_number_only = true)
 ```
 
 !!! note    

docs/src/parallel.md

@@ -47,7 +47,7 @@ There are different ways to deal with this issue:
 4. Increase the frequency of garbage collection calls:
    ```julia
    options = Options(GC=true, GC_threshold=0.5)
-   R = mddf(trajectory, options)
+   R = mddf(trajectory_file, solute, solvent, options)
    ```     
    The `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  

docs/src/python.md

@@ -93,7 +93,7 @@ The script to compute the MDDFs as associated data from within python is, then:
     To change the options of the calculation, set the `Options` structure accordingly and pass it as a parameter to `mddf`. For example:
     ```python
     options = cm.Options(bulk_range=(8.0, 12.0))
-    results = cm.mddf(trajectory, options)
+    results = cm.mddf(trajectory_file, solute, solvent, options)
     ```
     The complete set of options available is described [here](@ref options).
 

docs/src/quickguide.md

@@ -91,7 +91,7 @@ solvent selections, and running the calculation on the trajectory.
 To define the protein as the solute, we will use the PDBTools package,
 which provides a handy selection syntax. First, read the PDB file using 
 ```julia
-atoms = readPDB("./system.pdb")
+atoms = read_pdb("./system.pdb")
 ```
 Then, let us select the protein atoms (here we are using the `PDBTools.select` function):
 ```julia
@@ -140,7 +140,7 @@ are automatically recognized.
 If default options are used (as the bin size of the histograms, read all
 frames without skipping any), just run the `mddf` with:
 ```julia
-results = mddf(trajectory, Options(bulk_range=(8.0, 12.0)))
+results = mddf(trajectory_file, solute, solvent, Options(bulk_range=(8.0, 12.0)))
 
 ```
 Some optional parameters for the computation are available in the

docs/src/results.md

@@ -9,7 +9,7 @@ the MDDF, KB integrals, and atomic contributions. The following section
 will assume that the computation was performed by calling the `mddf`
 function with 
 ```julia
-results = mddf(trajectory, Options(bulk_range=(8.0, 12.0)))
+results = mddf(trajectory_file, solute, solvent, Options(bulk_range=(8.0, 12.0)))
 ``` 
 such that the `results` variable contain the `Result` data structure. By
 default, the histograms contain 500 bins (`binstep=0.002` and

docs/src/selection.md

@@ -21,7 +21,7 @@ For example, here we define a protein of a system as the solute:
 ```jldoctest
 julia> using ComplexMixtures, PDBTools
 
-julia> atoms = readPDB(ComplexMixtures.Testing.pdbfile);
+julia> atoms = read_pdb(ComplexMixtures.Testing.pdbfile);
 
 julia> protein = select(atoms, "protein");
 
@@ -62,7 +62,7 @@ For example, the solute can be defined with:
 ```julia
 using ComplexMixtures, PDBTools
 
-atoms = readPDB("system.pdb")
+atoms = read_pdb("system.pdb")
 
 indices, names = select_with_vmd("./system.pdb", "protein", vmd="/usr/bin/vmd")
 
@@ -112,7 +112,7 @@ Here, we illustrate this feature by presselecting the acidic and basic residues
 ```julia
 julia> using ComplexMixtures, PDBTools
 
-julia> atoms = readPDB(ComplexMixtures.Testing.pdbfile);
+julia> atoms = read_pdb(ComplexMixtures.Testing.pdbfile);
 
 julia> protein = select(atoms, "protein");
 
@@ -152,9 +152,7 @@ With these group selections predefined, the contributions of these groups to the
 can be retrived directly from the result data structure with, for example:
 
 ```julia-repl
-julia> trajectory = Trajectory(trajectory_file, solute, solvent)
-
-julia> result = mddf(trajectory, Options(bulk_range=(8.0, 12.0)));
+julia> result = mddf(trajectory_file, solute, solvent, Options(bulk_range=(8.0, 12.0)));
 
 julia> acidic_residue_contributions = contributions(result, SoluteGroup("acidic residues"))
 ```