Quick Start Guide

Here is how to easily set up your system and start with protex!

Important

If not already done, use the installation instructions to get protex. For purposes of this tutorial, it is important to have the VVIntegrator plugin installed!

protex works together with OpenMM to allow bond breaking and formation (i.e., for a proton transfer) during MD simulations. First, obtain an OpenMM simulation object. For purposes of this tutorial, we will use a helper function.

from protex.testsystems import generate_im1h_oac_system

simulation = generate_im1h_oac_system()

Afterwards, the main pathway is to specify the allowed transfers and which atoms are subject to the transfer using ProtexTemplates. Then wrap the simulation and templates into a ProtexSystem.

from protex.system import ProtexSystem, ProtexTemplates

allowed_updates = {}
allowed_updates[frozenset(["IM1H", "OAC"])] = {"r_max": 0.16, "prob": 0.994}
allowed_updates[frozenset(["IM1", "HOAC"])] = {"r_max": 0.16, "prob": 0.098}

IM1H_IM1 = {"IM1H": {"atom_name": "H7"},
             "IM1": {"atom_name": "N2"}}

OAC_HOAC = {"OAC" : {"atom_name": "O2"},
            "HOAC": {"atom_name": "HO2"}}

templates = ProtexTemplates([OAC_HOAC, IM1H_IM1], allowed_updates)
ionic_liquid = ProtexSystem(simulation, templates)

Note

In order to keep this tutorial simple, we are not using equivalent atoms here. See the detailed example or the API guide for how to include multiple (de-)protonable sites per residue.

Next, define the update method.

from protex.update import NaiveMCUpdate, StateUpdate

update = NaiveMCUpdate(ionic_liquid)
state_update = StateUpdate(update)

Optionally, you can define reporters for the simulation. Protex has a built-in ChargeReporter to report the current charges of all molecules, which can just be added to the simulation like all other OpenMM reporters.

from protex.reporter import ChargeReporter

save_freq = 200
charge_reporter = ChargeReporter(f"path/to/outfile", save_freq, ionic_liquid)
ionic_liquid.simulation.reporters.append(charge_reporter)

You can add additional OpenMM reporters to the ionic liquid object:

from openmm.app import StateDataReporter, DCDReporter
report_frequency = 200
ionic_liquid.simulation.reporters.append(DCDReporter(f"traj.dcd", report_frequency))
state_data_reporter= StateDataReporter(sys.stdout,
    report_frequency,
    step=True,
    time=True,
    potentialEnergy=True,
    kineticEnergy=True,
    totalEnergy=True,
    temperature=True,
    volume=True,
    density=False,
)
ionic_liquid.simulation.reporters.append(state_data_reporter)

Now you are ready to run the simulation and just call the update method whenever you like.

for i in range(10):
    ionic_liquid.simulation.step(1000)
    state_update.update(2)

🎊 Congratulations! 🎊

You ran your first protex simulation and manged to break and build bonds during an MD Simulation!