Solute-Solvent-Cossolvent system

Here, SolutionBoxUSC stands for Solute (U), Solvent (S), and Cossolvent (C). Concentrations can be given in molarity ("mol/L"), molar fraction ("x"), mass fraction ("w/w" or "mm"), or volume fraction ("v/v" or "vv"); see Concentration Unit Conversion for the full list of unit aliases.

The example below: the polymer in water and ethanol, at a molar fraction of ethanol of 0.5: one in ten ethanol molecules (green) and the oxygen atoms of one in ten water molecules (light blue) (drag to rotate, scroll to zoom).

Packmol.SolutionBoxUSC — Type
SolutionBoxUSC(; 
    solute_pdbfile::String, 
    solvent_pdbfile::String,
    cossolvent_pdbfile::String,
    density_table::Matrix{<:Number},
    concentration_unit = "x",
    solute_molar_mass = nothing, # optional
    solvent_molar_mass = nothing, # optional
    cossolvent_molar_mass = nothing, # optional
)

Setup a system composed of a solute (U) a solvent (S) and a cossolvent (C).

The concentration units of the density table can be provided explicitly and are assumed by default to be the molar fraction, x, of the cossolvent. The density units are assumed to be g/mL unless the values are explicitly provided with Unitful units.

The molar masses of the solute, solvent, and cossolvent can be provided manually. If not, they will be computed from the atom types in the PDB file.

source
Packmol.packmol — Method
packmol(
    system::SolutionBoxUSC;
    concentration::Number,
    concentration_units::Union{Nothing,String} = nothing,
    output="system.pdb",
    # box size
    box_sides::AbstractVector{<:Number}, # or
    margin::Number,
    pbc::Symbol = :cubic, # or :orthorhombic, :dodecahedral, :octahedral
    kwargs...,
)

Builds and packs a Solute + Solvent + Cossolvent system, without writing an input file.

It is equivalent to calling write_packmol_input followed by packmol on the resulting file.

concentration, concentration_units, output, box_sides, margin, and pbc (see Cell shapes) behave as in write_packmol_input. Any other keyword (nloop, maxit, seed, ...) is forwarded to the packing engine — see packmol(::PackmolSystem).

Returns the built PackmolSystem, with the packing outcome in its .status field — see packmol(::PackmolSystem).

source
Packmol.write_packmol_input — Method
write_packmol_input(
    system::SolutionBoxUSC;
    concentration::Number,
    input="box.inp",
    output="system.pdb",
    # box size
    box_sides::AbstractVector{<:Number}, # or
    margin::Number,
    pbc::Symbol = :cubic, # or :orthorhombic, :dodecahedral, :octahedral
)

Function that generates an input file for Packmol.

The box sides are given in Ångströms, and can be provided as a vector of 3 elements. Alternatively, the margin can be provided, and the box sides will be calculated as the maximum and minimum coordinates of the solute plus the margin in all 3 dimensions.

pbc selects the shape of the periodic cell (see Cell shapes): :cubic (the default) forces all 3 sides to their maximum, :orthorhombic keeps box_sides/margin as given (possibly with unequal sides), and :dodecahedral/:octahedral build a rhombic dodecahedron/truncated octahedron cell (see dodecahedral_unitcell/ octahedral_unitcell): with margin, the smallest in which every atom of the solute (centered in the cell, in the orientation of its file) is at least margin from the faces of the cell, so that solutes of any shape fit in it; with box_sides, of minimum-image distance equal to their maximum.

source
Packmol.convert_concentration — Function
convert_concentration(system::SolutionBoxUSC, concentration, units::Pair{String,String})

Converts the concentration of the cossolvent between units.

The conversion is first(units) => last(units), using the density of the solution at that concentration (interpolated from the density table of the system) and the molar masses of the solvent and the cossolvent. The units are "mol/L" (molarity), "x" (molar fraction), "w/w" or "mm" (mass fraction), "v/v" or "vv" (volume fraction), or any of their aliases (see Concentration Unit Conversion). Molarities are returned with units.

Example

convert_concentration(system, 0.2, "x" => "mol/L")
source

Setting up the system properties

The density of the mixture as a function of cossolvent concentration is given as a table. Here, for a water/ethanol mixture, as a function of the molar fraction of ethanol:

using Packmoldensity_table = [#   x cossolvent (ethanol)     density (g/mL)             0.0000                 0.9981             0.0416                 0.9820             0.0890                 0.9685             0.1434                 0.9537             0.2066                 0.9369             0.2809                 0.9151             0.3695                 0.8923             0.4769                 0.8685             0.6098                 0.8450             0.7786                 0.8195             1.0000                 0.7906]
11×2 Matrix{Float64}:
 0.0     0.9981
 0.0416  0.982
 0.089   0.9685
 0.1434  0.9537
 0.2066  0.9369
 0.2809  0.9151
 0.3695  0.8923
 0.4769  0.8685
 0.6098  0.845
 0.7786  0.8195
 1.0     0.7906

We then initialize the system data structure, given the PDB files of one molecule of the solute, the solvent (water), and the cossolvent (ethanol):

test_dir = Packmol.RecipesDirectory * "/test"system = SolutionBoxUSC(    solute_pdbfile = "$test_dir/data/poly_h.pdb",    solvent_pdbfile = "$test_dir/data/water.pdb",    cossolvent_pdbfile = "$test_dir/data/ethanol.pdb",    density_table = density_table,    concentration_units = "x", # molar fraction)
==================================================================
SolutionBoxUSC properties (Solute + Solvent + Cossolvent):
==================================================================
    Solute pdb file: poly_h.pdb
    Solvent pdb file: water.pdb
    Cossolvent pdb file: ethanol.pdb
    Molar masses: 
        solute: 5612.801f0 g mol^-1
        solvent: 18.01534f0 g mol^-1
        cossolvent: 46.069218f0 g mol^-1
    Concentration units: x
    Concentration range: 0.0 - 1.0
    Density range: 0.9981 g mL^-1 - 0.7906 g mL^-1
==================================================================

As with SolutionBoxUS, molar masses are computed from the PDB files unless given explicitly.

Packing the system

The system is built and packed directly, at a target cossolvent concentration:

packmol(system; concentration = 0.5, margin = 20.0, output = "system.pdb")

with concentration the molar fraction of ethanol (the units of the density table). This gives the system shown at the top of this page.

concentration_units can be passed to interpret concentration in units other than the density table's own (e.g. request a concentration in "mol/L" even though the table above is indexed by molar fraction). margin, box_sides, and pbc behave as in SolutionBoxUS.

Converting concentrations

convert_concentration converts a concentration of the cossolvent between units, using the density of the solution at that concentration (interpolated from the density table) and the molar masses of the components. For example, the molarity of ethanol at a molar fraction of 0.5:

convert_concentration(system, 0.5, "x" => "mol/L")
13.48866825794416 mol L^-1

convert_density_table! changes the units in which the system takes and shows the concentrations: after it, concentration in packmol (and write_packmol_input) is read in the new units, and get_density_table returns the table in them:

convert_density_table!(system, "mol/L")get_density_table(system)
11×2 Matrix{Float64}:
  0.0      0.9981
  2.12962  0.982
  4.20222  0.9685
  6.2056   0.9537
  8.12907  0.9369
  9.92643  0.9151
 11.617    0.8923
 13.1931   0.8685
 14.6709   0.845
 16.0084   0.8195
 17.1611   0.7906
Volume fractions

The volume fraction is the IUPAC one: the volume of the pure cossolvent divided by the sum of the volumes of the pure components, before mixing. Computing it requires the densities of the pure solvent and cossolvent, so the density table must include both (concentrations 0 and 1 in molar fraction).

Writing a Packmol input file

Instead of packing the system, write_packmol_input writes the input file of Packmol for it, to be inspected, edited or run later (see Writing a Packmol input file):

write_packmol_input(    system;    concentration = 0.5, # molar fraction of ethanol    margin = 20.0,    input = "box.inp",    output = "system.pdb",)
==================================================================
Summary:
==================================================================

Target concentration = 0.5 mol L^-1
(of cossolvent)      = 0.009188752730823752 (molar fraction)
                     = 0.023166193181015482 (mass fraction)

Box volume = 1.677100110841e6 Å^3
Solution volume = 1.6677620936347786e6 Å^3
Solute extrema = [ -38.685 Å, -24.895 Å, -39.405 Å, 38.685 Å, 24.895 Å, 39.405 Å ]
Periodic box (pbc = :cubic) = a = 118.81 Å, b = 118.81 Å, c = 118.81 Å
    α = 90.0°, β = 90.0°, γ = 90.0°

Density of solution = 0.5985848514066395 g Å^-3 mol^-1
Solute molar mass = 5612.801f0 g mol^-1
Cossolvent molar mass = 46.069218f0 g mol^-1
Solvent molar mass = 18.01534f0 g mol^-1

Number of cossolvent (ethanol.pdb) molecules = 502
Number of solvent (water.pdb) molecules = 54130

Final cossolvent concentration = 0.4998258534012574 mol L^-1
                            = 3322.2352462844196 Å^3 per molecule.
Final solvent concentration = 53.895564630697336 mol L^-1
                            = 30.810310246347292 Å^3 per molecule.

Final molar fraction = 0.00918875384390101

==================================================================

Wrote file: box.inp

==================================================================