Edit configuration
==================

The ``editconf`` tool edits the **simulation box configuration** for a PDB file.
It allows:

- scaling box dimensions  
- assigning new absolute box lengths  
- selectively applying PBC unwrapping along x / y / z  
- re-centering coordinates in the new box  
- producing a clean, corrected PDB file  

This is the DROPPS/CGPS re-implementation of the classic GROMACS ``editconf``.
The tool is implemented in ``editconf.py``.


Overview
--------

``dps editconf`` performs the following operations:

1. Read a **PDB** structure and its box vectors.  
2. Parse user options for box resizing:  
   - set absolute length (e.g., ``--x-axis 50``)  
   - multiply current box (e.g., ``--multiply-x-axis 2``)  
3. Optionally unwrap coordinates using PBC for each dimension independently.  
4. Expand the simulation box if requested.  
5. Translate all atoms so the structure is centered in the new box.  
6. Write the resulting frame to a new PDB file.

Key features:

- **Axis-specific** PBC control (treat x / y / z independently)  
- **Mutual exclusion** between setting absolute size and multiplying size  
- **Automatic coordinate recentering**  
- **Full preservation** of PDB metadata (atom order, residue info, chain IDs)  

The tool is ideal for:

- preparing larger boxes for new simulations  
- removing periodic wrapping before analysis  
- re-centering protein condensates or polymers  
- visual inspection / debugging of box geometry  


Usage
-----

Set a new box size:

.. code-block:: bash

   dps editconf -f system.pdb -o newbox.pdb -x 50 -y 50 -z 50

Double the box in x and y:

.. code-block:: bash

   dps editconf -f frame.pdb -o expanded.pdb -mx 2 -my 2

Unwrap only along z:

.. code-block:: bash

   dps editconf -f conf.pdb -o unwrapped.pdb -pz


Arguments
---------

Required
--------

.. option:: -f, --structure FILE

   Input PDB structure.  
   Must contain CRYST1 or BOX metadata readable by DROPPS.

.. option:: -o, --output FILE

   Output PDB filename.  
   If the extension is missing, ``.pdb`` is automatically added.


Box resizing
------------

Each axis may optionally specify:

**Absolute length (nm)**  
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. option:: -x, --x-axis INT  
.. option:: -y, --y-axis INT  
.. option:: -z, --z-axis INT

**Multiplicative scaling**  
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. option:: -mx, --multiply-x-axis INT  
.. option:: -my, --multiply-y-axis INT  
.. option:: -mz, --multiply-z-axis INT

**Important constraints**

For each axis, the script enforces:

- You **cannot** set absolute length *and* multiplier simultaneously  
- You **cannot** shrink the box (output length must be > original length)


PBC treatment
-------------

Each axis can independently unwrap periodic positions:

.. option:: -px, --treat-pbc-x  
.. option:: -py, --treat-pbc-y  
.. option:: -pz, --treat-pbc-z

When unwrapping is performed:

.. code-block:: python

   new_coordinates[:, i] = unwrap_pbc(atoms, box)[:, i]

Important details:

- If the box is expanded (e.g., ``-mx 2``), the tool **forces** unwrapping on that axis  
- If the user does *not* request unwrapping but box expansion requires it, the program prints:

  ::

     ## PBC for x axis treated although input says don't.


Workflow Details
----------------


(1) **Read input PDB**

.. code-block:: python

   atoms, box = read_pdb(args.structure)
   pdb_data = phrase_pdb_atoms(atoms, box)

(2) **Determine box change for each axis**

For axis X:

.. code-block:: python

   if args.x_axis and args.multiply_x_axis:
       ERROR

   if args.x_axis: 
       output_x = args.x_axis * nanometer
   elif args.multiply_x_axis:
       output_x = args.multiply_x_axis * raw_x
   else:
       output_x = raw_x

Same logic applies to y and z.

(3) **Apply PBC unwrapping if requested or required**

.. code-block:: python

   pbc_treated_coordinates = unwrap_pbc(atoms, box)

(4) **Validate expansion**

If expansion is requested but the new box is ≤ original box:

::

   ERROR: Cannot expand x axis from X to Y.

(5) **Re-center coordinates in new box**

Translation:

.. code-block:: python

   x_trans = (output_x - raw_x) / 2
   y_trans = (output_y - raw_y) / 2
   z_trans = (output_z - raw_z) / 2

New coordinate:

.. code-block:: python

   new_x = new_coordinates[:,0] + x_trans
   new_y = new_coordinates[:,1] + y_trans
   new_z = new_coordinates[:,2] + z_trans

(6) **Write final PDB**

.. code-block:: python

   write_pdb(output_file_name, [output_x, output_y, output_z], ...)

Final output message:

::

   ## Output PDB file write to newbox.pdb.


Examples
--------

Expand only the z axis:

.. code-block:: bash

   dps editconf -f box.pdb -o box_z2.pdb -mz 2

Shrink attempt (invalid):

::

   dps editconf -f sys.pdb -o bad.pdb -x 20
   ERROR: Cannot expand x axis from 50 to a smaller/equal value of 20.

Expand + unwrap x, keep y and z untouched:

.. code-block:: bash

   dps editconf -f conf.pdb -o fixed.pdb -mx 3 -px


Error Messages
--------------

**“ERROR: x axis length and x axis multiplier cannot be specified together.”**  
Mutually exclusive options.

**“ERROR: Cannot expand X axis from A to a smaller/equal value of B.”**  
You must increase box size; shrinking is not allowed.

**Terminal errors from PDB parsing**  
If the input structure cannot be read.

**Metadata warnings**  
If unwrapping is forced even when user disabled it.


Summary
-------

``dps editconf`` provides a robust and flexible tool for editing simulation box
sizes and correcting periodic images. It supports:

- absolute and multiplicative box resizing  
- axis-specific PBC unwrapping  
- careful validation of dimension conflicts  
- automatic recentering in the new simulation box  
- fully preserved PDB metadata  

It is essential for preparing initial configurations, removing PBC artifacts,
and resizing simulation boxes in CGPS/DROPPS workflows.