cationize-protein

Build progressively cationized proteins and export structures and parameters for Amber, OpenMM or GROMACS.

Contents

• Getting started
• Usage and examples
• Data and files
• Methods and validation
• Documentation
• Citation
• Contributing
• Acknowledgements
• License

Note

Parameters, charges and topologies are preliminary. See the validation notes before using them in simulations.

Getting started

From the repository root, install the package in a Python 3.12 environment and run the bundled Asp–Glu–Leu example:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install .
python examples/quickstart/run_quickstart.py --output-dir work/quickstart

The example uses OpenMM minimization and the screened-Coulomb solver. Separate APBS, Amber and GROMACS installations are unnecessary for this run.

Quickstart and expected outputs · Installation guide · Optional software

Usage and examples

For your own protein, prepare the structure and then run progressive cationization:

cationize-protein prepare input.pdb --output prepared

cationize-protein run --pdb prepared/protein.pdb --output series

For input retrieval, preparation settings and explicit engine/solver selection, see the command reference.

• HSA series: existing structures, parameters and modification tables.
• Lysozyme walkthrough: retrieval, repair and cationization.
• All command-line options.

Data and files

What you need	Where to find it
Structure for inspection or docking	25/protein.pdb
Ready Amber protein	25/exports/system.parm7 and system.rst7
Ready OpenMM protein	25/exports/system.xml and state.json
Ready GROMACS protein	25/exports/system.top, system.gro, forcefield.itp, protein.itp
Single modified residue template	residue_templates/ASC.lib, GLC.lib, etc. (Amber OFF format)
Complete Amber protein unit & parameters	25/exports/protein.lib, parameters.frcmod, PARAMETERS.json

See output and parameter reuse for the complete file layout, or complex assembly to add an independently parameterized ligand.

Methods and validation

Chemical cationization reacts carboxylic acid groups (Asp and Glu side chains and the biological C-terminus) with ethylenediamine to form positively charged aminoethyl-amides (-C(=O)-NH-CH₂-CH₂-NH₃⁺), shifting each modified site from -1 to +1 (Δq = +2 e).

At each step, cationize-protein repeats four operations until all requested modification percentages (by default 0%, 25%, 50%, 75% and 100%) are reached:

1. Electrostatic ranking: computes the electrostatic potential around every unmodified carboxyl group and selects the site with the most negative accessible potential.
2. Amidation & steric search: replaces the selected carboxylate with the corresponding validated RESP aminoethyl-amide template and rotates torsional bonds to remove steric clashes while preserving the protein backbone and disulfides.
3. Energy minimization: relaxes the modified structure in implicit solvent (GBn2) with positional restraints on the native backbone.
4. Protonation check: re-evaluates native titratable residues (His, Asp, Glu, Cys, Lys, Tyr) with PROPKA at the target pH while keeping introduced ammonium groups protonated (+1).

HSA structures and electrostatic surfaces are shown for each cationization level. Amidation, minimization and protonation use fixed illustrative examples. View the image details.

---

The bundled library contains 32 chemical states covering modified Asp/Glu side chains and C termini across terminal, histidine and cysteine contexts (validation summary, parameter guide).

See methods, residue parameters and validation notes for the physical models, fitting protocol and current scientific limits.

Documentation

Topic index

• Quick navigation
• How it works
• Install
• Optional external software
• Get a structure or sequence
• Prepare a protein
• Disulfide verification from UniProt
• Optional structure modeling for missing loops/residues
• Run cationization
• Find your files
• Add a ligand
• Examples
• HSA example
• Lysozyme walkthrough
• Options
• Software and references
• Residue parameters

Topic	Guide
First example	Quickstart
Installation	Install
Complete commands and options	Command reference
Protein preparation	Preparation
Parameters and force fields	Parameters · Force fields
Output reuse and ligands	Outputs · Complexes
External programs	Optional software
Methods and limitations	Methods · Validation

Software and primary references.

Citation

If you use this software or its parameter libraries, cite the archived release:

Alessandro Calza (2026). cationize-protein, version 0.1.0. DOI: 10.5281/zenodo.24119586.

Citation metadata: CITATION.cff.

BibTeX

@software{Calza2026CationizeProtein,
  author = {Alessandro Calza},
  title = {cationize-protein},
  version = {0.1.0},
  year = {2026},
  doi = {10.5281/zenodo.24119586},
  url = {https://github.com/CalzaAlessandro/cationize-protein}
}

Contributing

See CONTRIBUTING.md for setup and checks. Report problems or propose changes through GitHub Issues. Include the affected file or command and a short description.

Acknowledgements

This work was developed within the NanoBio Interface Lab at the Department of Chemistry "Giacomo Ciamician," Alma Mater Studiorum – University of Bologna, and the Preclinical & Translational Research in Oncology lab (PRO), IRCCS Azienda Ospedaliero–Universitaria di Bologna.

License

This software, its bundled residue parameter libraries, example structures and documentation are released under the Apache License, Version 2.0 (Apache-2.0).

See CITATION.cff for citation metadata. Third-party software and reference force fields retain their original terms and attribution.