Introduction

Manually writing input files can be tedious. To facilitate this task, pyUAMMD has been developed. It is a Python library that adds tools for easily working with UAMMD-structured input files. pyUAMMD includes a single class, simulation, which behaves like a dictionary where different Sections and Data Entries of UAMMD-structured can be specified:

import pyUAMMD
sim = pyUAMMD.simulation()

sim["system"] = {}
...

sim["global"] = {}
...

sim["integrator"] = {}
...

sim["state"] = {}
sim["state"]["labels"] = ["id", "position", "direction"]
sim["state"]["data"] = []
for i in range(N):
    sim["state"]["data"].append([i, [0,0,0], [0,0,0,1.0]])

sim["topology"] = {}
sim["topology"]["structure"] = {}
sim["topology"]["structure"]["labels"] = ["id", "type"]
sim["topology"]["structure"]["data"] = []
for i in range(N):
    sim["topology"]["structure"]["data"].append([i, "A"])

sim["topology"]["forceField"] = {}
...
sim["simulationStep"] = {}
...

sim.write("simulation.json")

The simulation class has the write(...) method to write the dictionary content to a JSON file. Writing a dictionary to a JSON file is trivial in Python using the json library, but this is extremely slow. To address these restrictions, we have developed the JFIO (JSON Fast Input Output) library. It uses pybind11 to create a wrapper with C++ functions of nlohmann::json, enabling rapid writing and reading of JSON files where simulation parameters are set.

simulation also includes the append method, which allows different simulations to be merged into one. This method is central to the implementation of batching. With append, we add the content of another simulation (the added simulation) to the current one (reference simulation). The append method has two modes:

• “modelId”: In this mode, the added simulation is considered part of the same simulation. The result is configured so the number of batches does not increase. Contents of the added simulation (like particle IDs, group definitions, interaction parameters) are adjusted to make the resultant simulation viable. This method is useful for building complex simulations from simpler ones. For example, suppose we have two simulation files, sim1.json and sim2.json, each containing a different protein using the same model. We could create two simulation objects with pyUAMMD and then add them together. The resultant simulation would contain both proteins, and by adding an interaction potential between the them, it could be used to study their interaction.

• “batchId”: Using this mode, the two simulations are joined into one, but each is associated with a different batchId (in addition to configuring the rest of the parameters to make the simulation viable). This is the simplest way to use UAMMD-structured batching and allows for incorporating a large number of simulations into a single large simulation to execute the sub-simulations concurrently.

So far, we have shown how to use pyUAMMD to create simulations with the intention of finalizing this procedure by executing the write method, which writes a .json file containing the simulation input. This file is then used to run the UAMMDlauncher binary, initiating the simulation. But pyUAMMD also allows direct execution of the simulation from Python with the run method:

import pyUAMMD
sim = pyUAMMD.simulation()

sim["system"] = {}
...

sim.run()

This method starts the simulation, yielding a result analogous to using the binary. This approach is intended to make UAMMD-structured more accessible for less advanced users who may not be comfortable using a command line interface CLI. This implementation is straightforward with pybind11. Launching the simulation is fully functional and can be executed. It also serves to showcase the potential for integrating UAMMD-structured with Python. Future work aims to extend interoperability with Python, with the first objective being the ability to program simulation steps entirely in Python. This would allow users with basic Python knowledge to access simulation information in real-time to extract or process variables they consider to be relevant.