Generate mesh-like box

The genmesh tool constructs a regular 3D mesh of insertion points and places multiple molecular configurations (from PDB files) into these positions. It is designed for:

• building multi-chain initial states for CG or all-atom MD

• preparing mixture systems (e.g., 10 A molecules + 5 B molecules)

• generating large simulation boxes with well-separated molecules

• automated PDB + TOP generation for DROPPS/CGPS workflows

genmesh generates two output files:

1. A PDB conformation containing all inserted molecules

2. A corresponding GROMACS topology (.top) combining all input ITP files

The tool is implemented in genmesh.py.

Overview

The program accepts:

• multiple PDB files (one per molecule type)

• multiple ITP files (one per PDB)

• multiplicities (how many copies of each molecule to insert)

It then:

1. Computes each molecule’s bounding-box diameter

2. Determines a 3D mesh large enough to place all molecules

3. Ensures at least gap nm separation between them

4. Optionally shuffles insertion order

5. Centers all molecules in the final simulation box

6. Writes a combined multi-chain PDB

7. Produces a new .top file listing all included molecules

Mesh placement uses cubic grid points with coordinate offsetting and optional shuffling to randomize positions.

Usage

Minimal example:

dps genmesh \
    -f A.pdb B.pdb \
    -p A.itp B.itp \
    -n 10 5 \
    -g 1.0 \
    -oc system.pdb \
    -op system.top

Arguments

Required Input Files

-f, --structure FILES

One or more PDB files. Example:

-f A.pdb B.pdb C.pdb

-p, --topology FILES

Matching ITP files for the PDBs (same order).

-n, --number INTS

Number of copies to insert for each molecule type. Example:

-n 6 3 1   # 6×A, 3×B, 1×C

Mesh & Geometry

-g, --gap FLOAT

Minimum spacing between molecules (nm).

-mesh, --mesh X Y Z

Explicit mesh size. If omitted, genmesh automatically guesses a cubic mesh large enough to hold all molecules:

\[N_\text{mesh} = \lceil \sqrt[3]{N_\text{total}} \rceil\]

-bt, --box-type {xy, cubic, anosotropy}

Type of final box. (Currently anosotropy is used; box edges are independently determined.)

-mx, --minimum-x

-my, --minimum-y

-mz, --minimum-z

Minimum allowed box lengths (nm). Ensures the final box is at least this large.

Randomization

-s, --shuffle

Shuffle the order of mesh point assignment before insertion.

Output Files

-oc, --output-conformation FILE

Output PDB filename (.pdb added automatically if needed).

-op, --output-topology FILE

Output .top filename (.top added automatically if needed).

Program Workflow

1. Validate inputs

Ensure the lengths of:

• structure list

• topology list

• molecule count list

are identical.

2. Load PDB molecules

molecule_list = [read_pdb(file)[0] for file in args.structure]

If any fail:

## An exception occurred when trying to open structure file.

3. Report molecule sizes

For each molecule:

• number of residues

• number of copies requested

4. Determine mesh size

If no explicit mesh given:

mesh = [M, M, M]
M = ceil((total_molecules)**(1/3))

Error if mesh capacity < total molecules.

5. Compute bounding-box diameter

Largest extent among x, y, or z across all molecules:

diameter = ceil(max(over all molecules: Δx, Δy, Δz))

Spacing between mesh points:

distance_between_mesh_point = ceil(diameter + gap)

6. Determine box size

Initial estimate:

box_size_mesh = mesh[i] * distance_between_mesh_point + gap

Final box size respects minimum-x/y/z constraints.

7. Generate mesh points

Mesh points arranged as:

[diameter/2 + (diameter+gap)*x_index, ...]

Shuffled if --shuffle is active; otherwise, lexicographic ordering.

Re-centered:

mesh_points = mesh_points_raw - mean(mesh_points_raw)

8. Write multi-molecule PDB

The script loops through all molecules and all replicas:

• assigns new chain IDs

• assigns atom indices sequentially

• applies coordinate shifts based on mesh point and box center

• preserves atom/residue names

• stores per-molecule lengths for writing

Final writing:

write_pdb(output.pdb, box_size, ...)

9. Write combined topology (.top)

The output system.top contains:

• [ itp files ] section listing unique ITP files

• [ system ] section listing molecule types and total counts

If duplicate molecule names appear across input ITPs:

## WARNING: Duplicate molecule name found in topology files.
## These files will be merged.

The code merges duplicates by summing their molecule counts.

Example

Example 1: two molecule types

dps genmesh \
    -f A.pdb B.pdb \
    -p A.itp B.itp \
    -n 12 8 \
    -g 0.8 \
    -oc mix.pdb \
    -op mix.top

Example 2: explicit mesh (3×3×2)

dps genmesh \
    -f chain.pdb \
    -p chain.itp \
    -n 10 \
    -mesh 3 3 2 \
    -oc box.pdb \
    -op box.top

Example 3: random placement

dps genmesh \
    -f protA.pdb protB.pdb \
    -p A.itp B.itp \
    -n 4 2 \
    -s \
    -g 1.5 \
    -oc rand.pdb \
    -op rand.top

Error Messages

“ERROR: Number of structure, topology, and number not match.” Input lists must align.

“ERROR: The required mesh X*Y*Z cannot contain N molecules.” Mesh too small.

“An exception occurred when trying to open structure file.” PDB could not be read.

Warning: Duplicate molecule names Shown when combining ITP files with the same molecule_name.

Summary

dps genmesh is a robust generator of large, multi-molecule initial configurations. Features include:

• support for multiple molecule types

• automatic or user-defined 3D meshes

• precise bounding-box–based spacing

• optional randomization

• automatic topology merging and writing

• correct unit handling and box-size determination

It is essential for building multi-chain initial states for CGPS / DROPPS simulations, especially for LLPS systems or complex mixtures.