API reference

Auto-generated from the pimms.lemonade docstrings.

Loading

pimms.lemonade.load(xtc=None, pdb=None, keyfile=None, *, spacing=None, dimensions=None, hardwall=None, temperature=None, start=None, stop=None, step=None, n_frames=None, verbose=False)

Load a PIMMS trajectory and return a LatticeTrajectory.

Parameters:

• xtc, pdb, keyfile (str or None) – Paths. xtc requires pdb (mdtraj needs a topology). pdb alone loads a single frame. keyfile is optional but authoritative for spacing / dimensions / hardwall / chain types.

• spacing, dimensions, hardwall (optional overrides) – Bypass the keyfile / inference for the lattice spacing (angstroms), the box dimensions (2- or 3-tuple), and the hardwall flag.

• start, stop, step (int, optional) – Frame slice applied at load time.

• n_frames (int, optional) – If given (and smaller), evenly subsample down to this many frames.

• verbose (bool) – Print a one-line load summary (including the lattice round-off residual).

The object hierarchy

class pimms.lemonade.LatticeTrajectory(store)

asphericity()

(n_frames, n_chains) per-chain asphericity for every frame.

center_of_mass()

(n_frames, n_chains, n_dim) per-chain COM for every frame.

end_to_end_distance()

(n_frames, n_chains) per-chain end-to-end distance for every frame.

property positions

Raw integer positions, (n_frames, n_atoms, 3).

radius_of_gyration()

(n_frames, n_chains) per-chain Rg for every frame.

property temperature

Simulation temperature (== k_B T in PIMMS reduced units), or None.

whole_positions()

Positions with every chain made whole across PBC, (n_frames, n_atoms, 3).

class pimms.lemonade.Frame(store, frame_index)

property clusters

Connected-component clusters (list of Cluster), largest first.

property droplet

The largest cluster in this frame (the condensate), or None if empty.

property grid

A dimensions-shaped int grid for this frame (site = chain index + 1).

property positions

Raw integer positions of every bead this frame, (n_atoms, 3) view.

class pimms.lemonade.Polymer(store, frame_index, chain_index)

distance_map()

Full (L, L) inter-bead Euclidean distance matrix (whole coords).

internal_scaling()

(separations, mean_distance) internal-scaling profile.

property positions

Raw (wrapped) integer lattice positions, (L, 3) view.

property straddles_boundary

True if any bond crosses a periodic boundary in the raw positions.

property whole_positions

Positions made contiguous across periodic boundaries, (L, 3).

class pimms.lemonade.Cluster(store, frame_index, chain_indices)

property bead_type_composition

dict bead_type_char -> count across all beads in the cluster.

property chain_type_composition

dict chain_type -> count.

property density

Beads per convex-hull volume (-1 if degenerate).

property positions

Raw (wrapped) positions of every bead in the cluster, (n_beads, 3).

radial_density_profile(minimum_cluster_size_in_beads=None)

Radial occupancy profile about the cluster COM (see PIMMS).

single_image_positions()

Cluster gathered into one periodic image, (n_beads, n_dim) (cached).

property sphericity

Isoperimetric sphericity of the convex hull, in (0, 1] (1 = a perfect sphere/circle). nan if the hull volume/area is degenerate.

3D: pi**(1/3) (6 V)**(2/3) / A. 2D: 4 pi A / P**2 (V is area, A is perimeter).

property volume

Convex-hull volume (-1 if the cluster is too small / degenerate).

Phase separation

Phase-separation and droplet-physics analysis for lemonade trajectories.

This module quantifies liquid-liquid phase separation of a PIMMS lattice system: the coexistence (binodal) densities of the dense and dilute phases, the condensed fraction and cluster-size order parameters, interfacial width, and droplet shape.

Two complementary geometries are supported:

• Droplet (spherical) - a radial density profile about the largest cluster’s centre of mass, fit to rho(r) = 1/2(rho_d + rho_v) - 1/2(rho_d - rho_v) tanh((r - R)/w) to extract the dense density rho_d, the dilute (vapour) density rho_v, the droplet radius R and the interface width w.

• Slab - a 1D density profile along the box’s long axis (the geometry of the slab_phase_separation demo), slabs re-centred per frame and fit to a two-interface tanh to extract the same coexistence quantities.

Densities are volume fractions (occupied lattice sites per available lattice site), so rho runs 0..1 and is directly comparable across box sizes.

Typical use:

from pimms.lemonade import phase_separation as ps
result = ps.analyze(traj)          # everything, auto-detecting the geometry
r, rho = ps.radial_density_profile(traj)
fit = ps.fit_radial_profile(r, rho)

class pimms.lemonade.phase_separation.BinodalFit(rho_dense: float, rho_dilute: float, interface_width: float, radius: float = nan, half_width: float = nan, success: bool = True)

Result of a tanh fit to a density profile.

class pimms.lemonade.phase_separation.PhaseSeparationResult(geometry: str, condensed_fraction: float, condensed_fraction_series: numpy.ndarray, n_clusters: float, largest_cluster_beads: float, binodal: pimms.lemonade.phase_separation.BinodalFit, shape: dict, profile: tuple = None)

property is_phase_separated

a clear density gap and most material condensed.

Type:

Heuristic

pimms.lemonade.phase_separation.analyze(traj, geometry='auto', min_beads=2)

Run the full phase-separation analysis and return a PhaseSeparationResult.

geometry is 'sphere', 'slab' or 'auto' (slab if one box axis is noticeably longer than the others, else spherical).

pimms.lemonade.phase_separation.cluster_size_distribution(traj, by='beads', min_beads=1)

All cluster sizes pooled across frames, as one flat array (for histograms).

pimms.lemonade.phase_separation.condensed_fraction(traj, min_beads=1)

Per-frame fraction of all beads that sit in the single largest cluster.

Returns (n_frames,). This is the basic phase-separation order parameter: ~0 in a well-mixed phase, ->1 when most material is in one condensate.

pimms.lemonade.phase_separation.droplet_shape(traj, min_beads=2)

Frame-averaged largest-cluster geometry.

Returns a dict of mean radius of gyration, asphericity, sphericity, convex-hull volume and density (each averaged over the frames that contain a cluster).

pimms.lemonade.phase_separation.fit_radial_profile(radii, density)

Fit a spherical droplet profile; returns a BinodalFit.

pimms.lemonade.phase_separation.fit_slab_profile(coord, density)

Fit a slab (two-interface) profile; returns a BinodalFit.

pimms.lemonade.phase_separation.largest_cluster_size(traj, by='beads', min_beads=1)

Per-frame size of the largest cluster (by='beads' or 'chains').

pimms.lemonade.phase_separation.number_of_clusters(traj, min_beads=2)

Per-frame count of clusters with at least min_beads beads.

pimms.lemonade.phase_separation.radial_density_profile(traj, bin_width=1.0, r_max=None, min_beads=2)

Spherically averaged density profile about the largest cluster’s COM.

For every frame the minimum-image distance of every bead from the condensate centre of mass is binned into radial shells and normalised by the number of lattice sites in each shell, giving a volume-fraction profile that falls from the dense core to the dilute background. Profiles are averaged over frames.

Returns:

(radii, density) – Shell-centre radii and the frame-averaged occupied fraction rho(r).

Return type:

tuple of 1D arrays

pimms.lemonade.phase_separation.slab_density_profile(traj, axis=None, min_beads=2)

1D density profile (volume fraction) along axis (default: the longest box axis), with the dense slab re-centred each frame so it does not smear out as the slab diffuses.

Returns:

(coordinate, density) – Lattice coordinate along the axis and the frame-averaged occupied fraction.

Return type:

tuple of 1D arrays

Surface tension

Surface-tension estimation from interfacial undulations (capillary-wave theory).

Two geometries, both driven by the fluctuation spectrum of the condensate’s interface:

• Slab (slab_surface_tension) - the condensate spans the periodic in-plane directions and is bounded along one axis, giving two nearly-flat interfaces whose height field h(x, y) obeys <|h(q)|^2> = kT / (gamma A q^2). Fitting the low-q capillary spectrum gives gamma. This is the robust method.

• Droplet (droplet_surface_tension) - a compact cluster whose radius R(theta, phi) fluctuates in spherical-harmonic modes with <|u_lm|^2> = kT / (gamma R0^2 (l-1)(l+2)) for l >= 2. Best-effort: it needs a single, well-formed, reasonably large droplet and many frames to be reliable.

Because PIMMS uses exp(-dE / T) (k_B = 1, energies in interaction units), the temperature is k_B T directly and gamma comes out in reduced units (interaction energy per lattice area). Temperature is taken from the trajectory (the keyfile TEMPERATURE) unless passed explicitly.

class pimms.lemonade.surface_tension.SurfaceTension(gamma: float, method: str, temperature: float, n_modes: int, gamma_std: float = nan, spectrum: tuple = None)

Result of a capillary-wave surface-tension estimate (reduced units).

pimms.lemonade.surface_tension.droplet_surface_tension(traj, l_max=5, n_polar=8, n_azim=16, min_beads=30, temperature=None)

Estimate surface tension from droplet shape (spherical-harmonic) fluctuations.

For each frame the largest cluster is centred on its COM and its interface radius R(theta, phi) sampled on an angular grid; the dimensionless fluctuation R/R0 - 1 is projected onto real solid-angle-weighted spherical harmonics. <|u_lm|^2> (averaged over m and frames) is fit to kT / (gamma R0^2 (l-1)(l+2)) for l = 2..l_max.

NOTE: reliable only for a single, compact, reasonably large droplet sampled over many frames; small/rough/multi-droplet systems give noisy estimates. Returns a SurfaceTension whose spectrum is (l, <|u_l|^2>).

pimms.lemonade.surface_tension.slab_surface_tension(traj, axis=None, min_beads=2, n_modes=8, temperature=None)

Estimate surface tension from the slab interface capillary spectrum.

Returns a SurfaceTension. n_modes is the number of lowest-q Fourier modes used (the capillary regime); gamma = N kT / <P(q) q^2> with N = Lx*Ly and P the frame/interface-averaged |FFT(delta h)|^2.

pimms.lemonade.surface_tension.surface_tension(traj, geometry='auto', temperature=None, **kwargs)

Estimate surface tension, dispatching on geometry ('slab' / 'droplet' / 'auto'; auto uses the box shape - slab if one axis is >= 1.5x the others).