htmd.membranebuilder.build_membrane module#

htmd.membranebuilder.build_membrane.buildMembrane(xysize, ratioupper, ratiolower, waterbuff=20, platform='CUDA', minimize=0, equilibrate=0, outdir=None, lipidf=None, forcefield_files=None, seed=None, solute=None, timestep_fs=2.0, head_z=15.0, head_restraint_k=0.0)#

Construct a membrane bilayer containing arbitrary lipid species and ratios.

Lipids are placed using a Lennard-Jones fluid simulation that distributes heads on a 2D plane before full 3D assembly. The upper and lower leaflets are built independently so they can carry different lipid compositions. An optional solute (typically a transmembrane protein) can be provided; the membrane is then built around it and lipids near the protein are rotationally optimized to avoid clashes. After assembly the system is solvated and, optionally, minimized and equilibrated with OpenMM.

Parameters:

  • xysize (list | ndarray) – XY dimensions of the membrane in Angstroms, e.g. [100, 100].

  • ratioupper (dict) – Lipid composition of the upper leaflet. Keys are lipid residue names (matching entries in the lipid library) and values are relative molar ratios, e.g. {'POPC': 10, 'CHL1': 1}.

  • ratiolower (dict) – Lipid composition of the lower leaflet, same format as ratioupper.

  • waterbuff (float) – Thickness in Angstroms of the water layer added above and below the membrane along the Z axis.

  • platform (str) – OpenMM platform used for the LJ-fluid lipid placement and any minimization or equilibration. One of 'CUDA', 'OpenCL', 'CPU', or 'Reference'.

  • minimize (int) – Number of conjugate-gradient minimization steps to run before the L-BFGS minimizer. Pass 0 to skip minimization entirely.

  • equilibrate (float) – Length of NPT equilibration in nanoseconds. Pass 0 to skip.

  • outdir (str | None) – Directory in which to write output PDB files. A temporary directory is created if not provided.

  • lipidf (str | None) – Path to the folder containing per-lipid CIF structures and the lipiddb.csv database file. Defaults to the htmd built-in library.

  • forcefield_files (list | None) – OpenMM ForceField XML files used during minimization and equilibration. Defaults to ["amber14/lipid17.xml", "amber14/tip3p.xml"].

  • seed (int | None) – Seed for the numpy random number generator. When provided the build is reproducible (conformer selection, initial rotations, and the Halton position shuffle). The OpenMM dynamics step is not seeded.

  • solute (Molecule | None) – Pre-positioned solute around which the membrane is built. The solute must be centered at z=0 (bilayer midplane). Lipids are packed around the solute footprint and are rotationally optimized to minimize clashes. The input Molecule is not modified.

  • timestep_fs (float) – Integrator timestep in femtoseconds for OpenMM equilibration. 2.0 fs is compatible with constraints=HBonds.

  • head_z (float) – Half-bilayer head-plane position in Angstroms. Every lipid head is initially placed at +head_z (upper leaflet) or -head_z (lower leaflet) to start from a flat bilayer geometry.

  • head_restraint_k (float) – Harmonic Z-restraint strength in kcal/mol/A^2 applied to lipid head atoms toward their initial head plane during minimization and equilibration. 0.0 disables the restraint.

Returns:

smemb – The assembled membrane system including surrounding water molecules.

Return type:

Molecule

Examples

>>> lipidratioupper = {'popc': 10, 'chl1': 1}
>>> lipidratiolower = {'popc': 8, 'chl1': 2}
>>> width = [50, 100]
>>> res = buildMembrane(width, lipidratioupper, lipidratiolower)
htmd.membranebuilder.build_membrane.equilibrateMembrane(mol, minimize=0, equilibrate_ns=0, platform_name='CUDA', forcefield_files=None, temperature=300, timestep_fs=2.0, solute=None, head_anchors=None, head_restraint_k=0.0, head_atoms=None, water_resname='HOH', water_oxygen_name='O')#

Minimize and/or equilibrate a solvated membrane with OpenMM.

Works both for membranes built by buildMembrane() and for user-supplied membranes (e.g. from CHARMM-GUI or another tool). The function detects the water naming used by mol and renames it to match the chosen force field XMLs. When head_restraint_k > 0 and no explicit head_anchors are given, anchors are auto-derived from the lipid head atoms in mol.

Equilibrated coordinates and the final box are written back into mol in place.

Parameters:

  • mol (Molecule) – Solvated membrane. Modified in place.

  • minimize (int) – Conjugate-gradient minimization steps before L-BFGS. Pass 0 to skip.

  • equilibrate_ns (float) – Length of NPT equilibration in nanoseconds. Pass 0 to skip.

  • platform_name (str) – OpenMM platform name. One of 'CUDA', 'OpenCL', 'CPU', or 'Reference'.

  • forcefield_files (list | None) – Force field XML files passed to openmm.app.ForceField. Defaults to ["amber14/lipid17.xml", "amber14/tip3p.xml"].

  • temperature (float) – Simulation temperature in kelvin.

  • timestep_fs (float) – Integrator timestep in femtoseconds.

  • solute (Molecule | None) – If given, heavy atoms in the membrane-spanning slab are added to the OpenMM System as frozen (mass=0) particles so that lipids relax around the solute. The solute Molecule is not modified.

  • head_anchors (list | None) – Explicit [(atom_idx, z_target_A), ...] anchors for the harmonic Z-restraint. When None and head_restraint_k > 0, anchors are auto-derived from the lipid head atoms in mol.

  • head_restraint_k (float) – Harmonic Z-restraint constant in kcal/mol/A^2 applied to lipid head atoms. 0.0 disables the restraint.

  • head_atoms (dict | None) – {resname: head_atom_name} mapping used when auto-deriving anchors. Defaults to the htmd lipid library map.

  • water_resname (str) – Water residue name expected by the force field XML. Water found in mol is renamed to this value on a working copy.

  • water_oxygen_name (str) – Water oxygen atom name expected by the force field XML. Water oxygen atoms found in mol are renamed on the working copy.

htmd.membranebuilder.build_membrane.listLipids()#

List all available lipids in the htmd lipid library.

Prints the path to the lipid library folder, the name of each available lipid, and the path to the lipiddb.csv database file.

Examples

>>> from htmd.membranebuilder.build_membrane import listLipids
>>> listLipids()
---- Lipids list: ...
htmd.membranebuilder.build_membrane.wrapping_dist_python(coor1, coor2, box)#

Compute minimum-image wrapped distances between a point and an array of points.

Parameters:

  • coor1 (ndarray) – Coordinates of the reference point or array of points.

  • coor2 (ndarray) – Coordinates of the target points.

  • box (ndarray) – Periodic box dimensions used to apply the minimum-image convention.

Returns:

distances – Array of wrapped Euclidean distances.

Return type:

ndarray