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:

.. code-block:: bash

   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
~~~~~~~~~~~~~~~~~~~~

.. option:: -f, --structure FILES

   One or more PDB files.  
   Example:

   .. code-block:: bash

      -f A.pdb B.pdb C.pdb

.. option:: -p, --topology FILES

   Matching ITP files for the PDBs (same order).

.. option:: -n, --number INTS

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

   .. code-block:: bash

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


Mesh & Geometry
~~~~~~~~~~~~~~~~

.. option:: -g, --gap FLOAT

   Minimum spacing between molecules (nm).

.. option:: -mesh, --mesh X Y Z

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

   .. math::

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


.. option:: -bt, --box-type {xy, cubic, anosotropy}

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

.. option:: -mx, --minimum-x  
.. option:: -my, --minimum-y  
.. option:: -mz, --minimum-z

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


Randomization
~~~~~~~~~~~~~

.. option:: -s, --shuffle

   Shuffle the order of mesh point assignment before insertion.


Output Files
~~~~~~~~~~~~

.. option:: -oc, --output-conformation FILE

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

.. option:: -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**

.. code-block:: python

   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:

.. code-block:: python

   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:

.. code-block:: python

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

Spacing between mesh points:

.. code-block:: python

   distance_between_mesh_point = ceil(diameter + gap)

(6) **Determine box size**

Initial estimate:

.. code-block:: python

   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:

.. code-block:: python

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

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

Re-centered:

.. code-block:: python

   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:

.. code-block:: python

   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

.. code-block:: bash

   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)

.. code-block:: bash

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

Example 3: random placement

.. code-block:: bash

   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.