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:

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

Double the box in x and y:

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

Unwrap only along z:

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

Arguments

Required

-f, --structure FILE

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

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

-x, --x-axis INT
-y, --y-axis INT
-z, --z-axis INT

Multiplicative scaling

-mx, --multiply-x-axis INT
-my, --multiply-y-axis INT
-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:

-px, --treat-pbc-x
-py, --treat-pbc-y
-pz, --treat-pbc-z

When unwrapping is performed:

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

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

  1. Determine box change for each axis

For axis X:

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.

  1. Apply PBC unwrapping if requested or required

pbc_treated_coordinates = unwrap_pbc(atoms, box)

  1. Validate expansion

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

ERROR: Cannot expand x axis from X to Y.

  1. Re-center coordinates in new box

Translation:

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

New coordinate:

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

  1. Write final PDB

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:

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:

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.