Vermouth and Martinize2

Martinize 2 is the primary CLI entry point for vermouth. It processes molecular structures through a 6-stage pipeline to prepare them for simulations:

1. Reading input files: Parsing .gro or .pdb files.
2. Repairing the input molecule: Completing the graph, fixing atom names, and identifying modifications.
3. Mapping to force field/resolution: Mapping the molecule to the desired output force field.
4. Applying Links: Generating inter-residue interactions.
5. Post-processing: Tasks like building an elastic network.
6. Writing output files.

Key Concept: Connectivity-based Identification Throughout the pipeline, the recognition and identification of atoms and particles are based on their connectivity (edges in a graph) in addition to their atom properties. A 'molecule' is treated as a connected graph of atoms and edges, which may include non-protein connections like disulphide bridges.

Interactions between residues are added using the vermouth.processors.do_links.DoLinks processor. This uses the concept of Links, which are molecular fragments describing interactions and the atoms they apply to.

Key Concepts

• Purpose: Links generate interactions that depend on local structure, such as protein sequence or secondary structure.
• Order of Application: Links can add, change, or remove interactions/nodes. They are applied in the order they are defined in the force field files. You should define links from most general to most specific.
• Matching Logic: For a link to match, all its node attributes must match.
• The 'order' attribute: This is a special case where attributes are translated to differences in residue numbers. For example, nodes BB and +BB must have a residue number difference of exactly 1. For non-linear polymers, you may need to use order specifications like > (greater than) or * (different from) to avoid complications.
• Overlapping Links: Links can overlap. For example, the link BB *BB will be applied both forwards and backwards.

The RepairGraph stage ensures the input molecule matches the reference force field's data:Block (including atom names and counts).

How Repair Works:

1. Atom Identification: Uses a Maximum Common Induced Subgraph (ISMAGS) algorithm to match input atoms to the reference. This handles both missing atoms and extra atoms (from PTMs).
2. Modification Identification: Atoms not recognized by the standard residue block are processed by CanonicalizeModifications. These are identified by finding an induced subgraph that matches a known data:Modification and contains at least one "anchoring" atom (an atom also described by a data:Block).

Warnings:

• unknown-residue: No data:Block found for a residue; the molecule will be removed.
• unknown-input: A modification cannot be identified; the involved atoms will be removed.

Note on Performance: ISMAGS is computationally expensive (exponential scaling). If using very large PTMs (e.g., lipidations), consider specifying them as separate residues to improve speed.

The resolution transformation converts your molecule to a target resolution (force field) using mappings. This is handled by the vermouth.processors.do_mapping.DoMapping processor.

How it works

• Mappings: The processor reads .map and .mapping files which describe how molecular fragments (nodes and edges) correspond to blocks in the target force field.
• Matching: For a fragment to match, atom and residue names must match the input molecule. It is highly recommended to run the Repair the input graph step before this to ensure you are using canonical atom names.
• Connectivity: Edges within blocks are taken from the target force field. Edges between blocks are generated based on the connectivity of the input molecule.
• Automatic Mappings: If the target force field (-ff) and the original force field (-from) are the same, mappings are generated automatically.

Warnings and Errors

• unmapped-atom: Issued if atoms in the input molecule (or non-hydrogen atoms) cannot be found in any mapping.
• inconsistent-data: A serious error issued if:
  • Multiple modification or block mappings overlap.
  • An output particle is constructed from input atoms with inconsistent residue-level attributes (e.g., different residue names/numbers).
  • An atom maps to multiple disconnected output particles.
  • An interaction is being set by multiple mappings.

Relevant CLI options:
- `-ff`: Target force field
- `-map-dir`: Directory containing mapping files

Processors are the fundamental building blocks of the martinize2 pipeline. To create a custom processor, you must implement either the run_system method or the run_molecule method from the vermouth.processors.processor.Processor class.

Choosing between run_system and run_molecule

• run_molecule (Preferred): Use this if your processor can operate on individual molecules independently. The default run_system implementation automatically iterates over all molecules in a system and calls run_molecule on each. This method must return a Molecule object (either a modified version of the input or a newly created one).
• run_system: Use this only if the task cannot be decomposed into per-molecule operations (e.g., operations that require knowledge of the entire system context). This method receives a System object, which is modified in place.

from vermouth.processors.processor import Processor

class MyCustomProcessor(Processor):
    def run_molecule(self, molecule):
        # Modify the molecule or create a new one
        # Must return a Molecule object
        return molecule

# OR

class MySystemWideProcessor(Processor):
    def run_system(self, system):
        # Modify the system in place
        pass