Surfaces given by points
within surface file distance [offset]
not within surface file distance [offset]
inside surface file [offset]
outside surface file [offset]A surface, or a curve, given by points in a file: the atoms are kept within distance (Å) of it, or farther than distance from it (not within). It is how membranes and compartments of any shape are built: the points of a triangulated surface, of a TS2CG model, of a shape drawn in a 3D editor or sampled from any function.
The file is relative to the directory of the input file, and holds a point per line, x y z or x y z nx ny nz (Å, with the normal of the surface at the point; lines starting with # are comments), or it is a point file of TS2CG (the .dat files of its PLM module, as point/OuterBM.dat, in nm: they are converted to Å).
With normals, the distance h to the surface is signed: positive on the side to which the normals point. Then offset shifts the surface along its normals, and the constraint is |h - offset| ≤ distance (within) or |h - offset| ≥ distance (not within). A single file of points of the middle of a bilayer, for example, defines where the heads of the lipids of both leaflets go (offsets of ±19 Å, for POPC), where the ends of their chains go (offset 0), and where the solvent goes (not within 24 Å of it). Without normals, h is the distance to the nearest point, and offset must be zero: for curves, or when the side of the surface does not matter.
The signed distance is smooth: near the surface it is the average of the distances to the tangent planes of the points within a smoothing radius (an implicit moving least squares surface), so that the points need not be dense, as long as they sample the shape: the default radius is 2.5 times the typical distance between neighboring points. On curved surfaces, the smoothing makes the surface slightly flatter: about r²/(10R) inwards, for a smoothing radius r and a radius of curvature R (0.2 Å, for r = 14 Å and R = 100 Å).
not within is the cheaper constraint: an atom with no point of the surface within the smoothing radius satisfies it (if distance + |offset| is not larger than the radius), without further search.
Inside and outside. For a closed surface whose normals point outwards (as those of the outer membrane of a vesicle of TS2CG, or of any closed shape), inside surface keeps the atoms inside it, h ≤ offset, and outside surface outside it, h ≥ offset. With offset, the region is bounded by the surface parallel to it at that distance along the normals: inside surface cell.dat -5.0 keeps the atoms 5 Å within the surface, outside surface cell.dat 3.0 3 Å beyond it. These constraints need normals, and the normals decide the side: they must point out of the enclosed region everywhere, and the surface must have no holes wider than the smoothing radius. Far from the surface, the side is that of a precomputed cell of the grid of the points, so that the solvent filling a large compartment costs little. For the initial placement and the volume tools, the region inside the surface is bounded by the box of its points.
In Julia code, the surface is a PointSurface, built from vectors of points and normals or read from a file with read_surface, and the constraints are WithinSurface, NotWithinSurface, InsideSurface and OutsideSurface. Several constraints can share a surface; in input files, constraints naming the same file share it.
Packmol.PointSurface — Type
PointSurface(points, normals = nothing; radius = nothing)A surface (or a curve) given by points, as an AbstractVector of 3D positions (Å), optionally with the normals at the points (any length: they are normalized). With normals, the distance to the surface is signed (positive on the side of the normals) and smooth; without them, it is the distance to the nearest point.
radius is the smoothing radius of the signed distance: the points within this distance of a position define the surface there. By default, 2.5 times the typical distance between neighboring points.
See read_surface, to read the points from a file, and WithinSurface and NotWithinSurface, for the constraints.
Packmol.read_surface — Function
read_surface(file; radius = nothing, T = Float64)Reads the points of a surface (a PointSurface) from a file:
- a point file of TS2CG (the
.datfiles written by itsPLMmodule, aspoint/OuterBM.dat): positions and normals, in nm, converted to Å; - a text file with a point per line:
x y zorx y z nx ny nz(Å; lines starting with#are comments).
radius is the smoothing radius of the signed distance (see PointSurface).
Packmol.surface_distance — Function
surface_distance(s::PointSurface, x)The distance of the position x to the surface s, signed if the surface has normals (positive on their side), and its gradient.
Packmol.WithinSurface — Function
WithinSurface(surface::PointSurface, distance; offset = 0.0, weight = 5.0)Keeps the atoms within distance (Å) of a surface given by points. With offset, the distance is to the surface parallel to it at the signed distance offset along its normals: |h - offset| ≤ distance, where h is the (signed) distance to the surface. Input file syntax: within surface file distance [offset].
Packmol.NotWithinSurface — Function
NotWithinSurface(surface::PointSurface, distance; offset = 0.0, weight = 5.0)The atoms farther than distance (Å) from the surface, or from the surface parallel to it at the signed distance offset along its normals: |h - offset| ≥ distance. Input file syntax: not within surface file distance [offset].
Packmol.InsideSurface — Function
InsideSurface(surface::PointSurface; offset = 0.0, weight = 5.0)Keeps the atoms inside a closed surface given by points. The normals must point outwards (as those of the outer membrane of a vesicle of TS2CG): h ≤ offset, where h is the signed distance to the surface (negative inside). With offset, the region is that of the surface parallel to it at that distance along the normals (negative: deeper inside). Input file syntax: inside surface file [offset].
Packmol.OutsideSurface — Function
OutsideSurface(surface::PointSurface; offset = 0.0, weight = 5.0)The atoms outside a closed surface given by points with normals pointing outwards: h ≥ offset, where h is the signed distance to the surface (positive outside). Input file syntax: outside surface file [offset].
Example
A bilayer of a coarse-grained lipid on a torus given by points with normals, half immersed in a pool of water, not within 12 Šof the middle of the bilayer. The lipid is a chain of 5 beads, 8 Šlong: the head (bead 1) goes at 9 Šfrom the middle surface, on either side, and the end of the chain (bead 5) near it. The numbers of lipids follow from the areas of the two leaflets (about 60 Ų per lipid). The box of the water, below z = 0, cuts the torus in half; its volume available to the water, given by free_volume, is 200400 ų: 6700 molecules at 1 g/mL.
structure lipid.pdb
number 530
atoms 1
within surface torus.dat 1.5 9.0
end atoms
atoms 5
within surface torus.dat 1.5
end atoms
end structure
structure lipid.pdb
number 115
atoms 1
within surface torus.dat 1.5 -9.0
end atoms
atoms 5
within surface torus.dat 1.5
end atoms
end structure
structure water.pdb
number 6700
not within surface torus.dat 12.0
inside box -60. -60. -30. 60. 60. 0.
end structureThe same system, packed with the Julia API and shown with the visualize function of PDBTools.jl. The points of the torus (radii of 35 and 14 Å around the z axis) are generated here, with their normals:
using Packmol, PDBTools# Points of the torus, about 1.5 Å apart, and the normalsR = 35.0 # radius of the ringr = 14.0 # radius of the tubepoints = NTuple{3,Float64}[]normals = NTuple{3,Float64}[]us = range(0, 2π; length = 200)[1:end-1]vs = range(0, 2π; length = 70)[1:end-1]for u in us, v in vs n = (cos(v) * cos(u), cos(v) * sin(u), sin(v)) push!(points, (R * cos(u) + r * n[1], R * sin(u) + r * n[2], r * n[3])) push!(normals, n)endtorus = PointSurface(points, normals)outer = structure_type("lipid.pdb"; number = 530, atom_constraints = [ [1] => WithinSurface(torus, 1.5; offset = 9.0), [5] => WithinSurface(torus, 1.5), ],)inner = structure_type("lipid.pdb"; number = 115, atom_constraints = [ [1] => WithinSurface(torus, 1.5; offset = -9.0), [5] => WithinSurface(torus, 1.5), ],)pool = InsideBox([-60., -60., -30.], [60., 60., 0.])water = structure_type("water.pdb"; number = 6700, constraints = [NotWithinSurface(torus, 12.0), pool],)system = PackmolSystem([outer, inner, water]; tolerance = 2.0, output = "torus.pdb",)packmol(system)visualize(get_atoms(system), # the heads "resname LIP and name C1" => (style = :spheres, color = "orange"), "resname LIP and not name C1" => (style = :spheres, color = "gray"), "water" => (style = :sticks, color = :element, water = true); rotate = [(:z, 30), (:x, -70)],)The beads of the lipid are 2 Å apart, too far for bonds to be drawn: they are shown as spheres.
Example: inside and outside
Water inside the same torus, and outside it, at least 3 Šaway from its surface, in the pool below z = 0. The volumes available to them, given by free_volume, are 135900 and 332800 ų: 4500 and 11100 molecules at 1 g/mL.
structure water.pdb
number 4500
inside surface torus.dat
end structure
structure water.pdb
number 11100
outside surface torus.dat 3.0
inside box -60. -60. -30. 60. 60. 0.
end structureinside = structure_type("water.pdb"; number = 4500, constraints = [InsideSurface(torus)],)outside = structure_type("water.pdb"; number = 11100, constraints = [OutsideSurface(torus; offset = 3.0), pool],)system = PackmolSystem([inside, outside]; tolerance = 2.0, output = "torus_water.pdb",)packmol(system)visualize(get_atoms(system), # the 4500 inside "index <= 13500" => (style = :spheres, color = "blue", water = true), "index > 13500" => (style = :sticks, color = :element, water = true); rotate = [(:z, 30), (:x, -70)],)