pyCHARMM: Embedding CHARMM Functionality in a Python Framework

Abstract

CHARMM is rich in methodology and functionality as one of the first programs addressing problems of molecular dynamics and modeling of biological macromolecules and their partners, e.g., small molecule ligands. When combined with the highly developed CHARMM parameters for proteins, nucleic acids, small molecules, lipids, sugars, and other biologically relevant building blocks, and the versatile CHARMM scripting language, CHARMM has been a trendsetting platform for modeling studies of biological macromolecules. To further enhance the utility of accessing and using CHARMM functionality in increasingly complex workflows associated with modeling biological systems, we introduce pyCHARMM, Python bindings, functions, and modules to complement and extend the extensive set of modeling tools and methods already available in CHARMM. These include access to CHARMM function-generated variables associated with the system (psf), coordinates, velocities and forces, atom selection variables and force field related parameters. The ability to augment CHARMM forces and energies with energy terms or methods derived from machine learning or other sources, written in Python, CUDA or OpenCL and expressed as Python callable routines is introduced together with analogous functions callable during dynamics calculations. Integration of Python-based graphical engines for visualization of simulation models and results is also accessible. Loosely coupled parallelism is available for workflows such as free energy calculations, using MBAR/TI approaches or high-throughput multisite λ-dynamics (MSλD) free energy methods, string path optimization calculations, replica exchange and molecular docking with a new Python-based CDOCKER module. CHARMM accelerated platform kernels through the CHARMM/OpenMM API, CHARMM/DOMDEC and CHARMM/BLaDE API are also readily integrated into this Python framework. We anticipate that pyCHARMM will be a robust platform for the development of comprehensive and complex workflows utilizing Python and its extensive functionality as well as an optimal platform for users to learn molecular modeling methods and practices within a Python-friendly environment such as Jupyter Notebooks.

Graphical abstract

Introduction

Understanding how biological macromolecular systems (proteins, nucleic acids, lipid membranes, carbohydrates, and their complexes) function is a major objective of current research by computational chemists and biophysicists. The utility of atomic models with realistic microscopic interactions in the investigation of biomolecules, as well as other chemical systems, has been established through what now represents nearly five decades of computational studies to address biological questions.¹ These methods and applications have been described in a plethora of books and reviews.^2–11 Moreover, such studies have now reached a point where computational models play an important role in the design and interpretation of experiments.¹² This is of particular importance where molecular simulations are used to obtain information that is difficult to determine experimentally.^13,14

With the continued evolution of the field of biomolecular simulation and the complexity of questions explored and phenomena investigated, maintaining maximum flexibility and availability of a wide range of computational methods for the exploration and integration of novel ideas in research and its applications is essential. Access to software platforms for the development and application of computational biophysical methods has spurred the introduction of several general-purpose programs distributed in academic and commercial environments. Many of these were described in two special issues of the Journal of Computational Chemistry (JCC)^15–20 and elsewhere.^21–23 Additionally, resources that enable complex simulation models of biological macromolecules to be set-up, run and analyzed have emerged, with CHARMM-GUI seeing the broadest range of functionality.^24–47

CHARMM (Chemistry at HARvard Molecular Mechanics) is a general and flexible molecular simulation and modeling program that uses classical (empirical, fixed charge and polarizable, and semi-empirical) and quantum mechanical (QM) (semi-empirical or ab initio) energy functions for molecular systems of many different classes, sizes, and levels of heterogeneity and complexity. This functionality is integrated into a single executable (approximately 1,000,000 lines of modular Fortran, C/C++, CUDA and OpenCL code) and calculations are accessed using CHARMM through the interpreted CHARMM scripting language. This feature in CHARMM is unique relative to the other major packages noted above, and has been provided since the introduction of CHARMM in 1983.⁴⁸ The script-level programmability of CHARMM has enabled many algorithmic ideas and complex simulation schemes to be tested and applied without the need to develop software routines to be compiled and integrated with the executable version of the program on a particular platform. This ability to prototype methodological ideas prior to committing them to code has been a key driver in the impressive range of methods available in CHARMM.

Within the CHARMM scripting language a set of command structures, including GOTO, STREam, and IF-ELSE-ENDIf structures, corresponding to the respective control-flow statements in most programming languages, provide the basis for the powerful high-level scripting function that permits the general and flexible control of complicated simulation protocols and facilitates the prototyping of new methods as just noted. The various functionalities of CHARMM can be combined in myriad ways using these command structures. The order of accessible CHARMM commands at any point in the script is controlled by the data required by the command. One example would be calculation of the energy: the energy cannot be calculated until i) the topology and parameter files describing the fragment (or residue) libraries needed to generate the system of interest are read; ii) the sequence of said residues is specified; iii) the data structures associated with that sequence are generated, i.e., the psf is read and any patching is performed; iv) and the coordinates are either built or read from a file. While other programs used in the field enable some of this flexibility through shell scripting or related interpreted language scripting that is exercised during the running of the program, these programs largely rely on fixed input files to describe a single computational workflow or rely on external programs and pre-processing to achieve related objectives. The programmability of CHARMM through its scripting language is unique and was instrumental in establishing both complex workflows in structure refinement as well as simplified interfaces for specific modeling tasks, both realized in the MMTSB ToolSet developed in 2004.⁴⁹

pyCHARMM Architecture, Organization and Functionality

Given the architecture of CHARMM and its extensive programmability using the CHARMM scripting language, it is a natural evolution to augment the CHARMM scripting language to leverage the popularity, familiarity and utility of the Python language.⁵⁰ This task was accomplished by implementing a thin API for calling CHARMM routines from Python, called pyCHARMM.

Installation of pyCHARMM starts with obtaining the latest version of the CHARMM source code and compiling CHARMM as a shared, callable library (as opposed to a binary executable). Separately, using the pip package manager, pyCHARMM – expressed as a Python package – is installed. To successfully complete the process, an environment variable called CHARMM_LIB_DIR is defined to inform the Python module of the location of the CHARMM shared library. It is this library that the modules of pyCHARMM use to access CHARMM functionalities. The detailed steps of installation are provided in the SI.

A successful installation of the pyCHARMM package in a location appropriate to Python creates a thin Python API - where each module consists of Python bindings to Fortran functions that collectively constitute a thin Fortran API, a.k.a. the pyCHARMM API. Through these functions, access is provided to the core CHARMM functionalities and users only interact directly with the Python API. This architecture, through careful marshalling, ensures that many of the key CHARMM data structures can be bi-directionally passed between the two APIs. Figure 1 illustrates the architecture of the installation. From the user’s end, calls to functions are made which eventually access Fortran/C++ routines in CHARMM via Python bindings to these routines. A Python binding in a module calls a Fortran function defined in a Fortran module file and they typically have a one-to-one relation. As Fortran routines are successfully executed, the returned data travel back to the end-user.

Figure 1:

pyCHARMM architecture. (Top) The end user writes a Python script to execute CHARMM commands by their Python expressions after importing the necessary Python modules in pyCHARMM. (Middle) The functions available to the user are the Python modules in the Python API, which in many cases represent bindings to the Fortran routines in the pyCHARMM API (or the Fortran module). The pyCHARMM API is a collection of Fortran modules that is included with the CHARMM source code.

The current pyCHARMM APIs consist of the functional components of CHARMM and provide the interfaces between CHARMM functionality and its expression in Python. For example, as illustrated in Figure 1, the API file api_coor.F90 provides an interface between CHARMM coordinate functionality as part of the coordinate manipulation commands (doc/corman.info) and the pyCHARMM commands, api_minimize.F90 interfaces with the CHARMM ABNR, SD and OpenMM (OMM) minimizers, api_generate.F90 contains the interface to Python instantiations of psf generation and manipulation commands (from doc/struct.info) and api_ic.F90 enables the internal coordinate manipulation commands from CHARMM (doc/ic.info). A list of current pyCHARMM APIs is presented in Table S1.

The CHARMM commands and functionality are then expressed through Python modules. These modules provide bindings to the CHARMM commands denoted by the module name and they must be imported into the python script before they can be used. For example import pycharmm.shake provides the Python bindings to set-up and execute the SHAKE command and import pycharmm.nbonds allows the manipulation of the non-bonded data structure (e.g., see doc/nbonds.info). Likewise, the module psf.py provides an interface to the psf-based data structures and access to the variables that reside within them. Table S2 lists the Python modules provided as part of the CHARMM distribution for use in pyCHARMM.

In the Python expression of CHARMM, the basic CHARMM scripting keywords have been largely maintained to provide continuity in the structure of CHARMM commands through pyCHARMM. This was deliberate to conveniently enable an experienced CHARMM user to transfer their current CHARMM scripts to pyCHARMM scripts as well as allow new CHARMM users to utilize the extensive libraries of CHARMM scripts that are available on the world-wide-web. The pyCHARMM modules can also be conveniently integrated with other functionalities from external Python modules and libraries for the creation of complicated frameworks for simulations and/or analyses. For instance, the module energy_func.py represents an abstraction of the CHARMM user energy term and enables one to call any user-supplied energy function at every energy evaluation during pyCHARMM execution. This function can also utilize Python interfaces to machine learned energy functions such as the TorchANI Neural Network Potential in PyTorch,⁵¹ as well as implementations of CUDA or OpenCL utilizing established Python APIs, e.g, NVIDIA CUDA Python 11.7.1, Numba, PyCUDA, and PyOpenCL.

A Python module in pyCHARMM typically represents a single command in CHARMM and is documented with `Docstrings`, which allow the user to access documentation at the command line or at the Python session prompt. Alternatively, a user can also visit pyCHARMM’s documentation located at https://github.com/clbrooksiii/pyCHARMM-Workshop that provides details about the usage of each Python module, the CHARMM commands they provide bindings to (with examples and links to the command’s documentation webpage), and their member functions along with their syntactic usage, input parameters and return values.

While the core of CHARMM functionality is directly represented by Python modules, in the present implementation not every CHARMM command is expressed by an explicit Python binding. Nevertheless, all CHARMM commands are available for use in Python scripting through the lingo.py module, which is an interface to the CHARMM script command interpreter. This module can also be combined with script.py to create callable custom python functions for repeated tasks.

Python Mapping of “Standard” Molecular Modeling Tasks in pyCHARMM

It is instructive to illustrate the correspondence between a simple task in CHARMM scripting language and pyCHARMM. In Figure 2, we illustrate this for the case of building a blocked alanine residue, minimizing its conformation in vacuum, and computing its energy. The emphasis is on the correspondence between the CHARMM script commands and the structure of the Python bindings to those commands. The close correspondence was a design feature instituted in this manner to allow users to take advantage of the wide range and distribution of CHARMM scripts as they begin learning to program their molecular modeling applications in pyCHARMM.

Figure 2:

Building an alanine dipeptide. An illustration of the correspondence between CHARMM scripting language commands and their expression as Python functions. Shown are the specific tasks of building the structure of Ala-dipeptide, assigning coordinates to it, and setting up a list of non-bonded interaction parameters for energy minimization calculations.

The tasks illustrated in Figure 2 also include reading the CHARMM topology and parameter files, reading a protein sequence, and in the end writing a CHARMM psf file and coordinates in CHARMM CARD and PDB formats. The Python bindings for such commands in pyCHARMM are contained in the read.py and write.py modules as noted in Table S2. Also included are psf generation and terminal patching, non-bonded specification, energy calculation and minimization.

A key point to note from this illustrative example is the order in which pyCHARMM functions can be called. When using pyCHARMM, Pythonic functions – Python expressions of the CHARMM commands – must be called in the same order in which the corresponding CHARMM commands would typically be called. For instance, functions to read the topology and parameter files must precede functions to build or read the structures (using one of the many ‘struct’ module commands like READ SEQUence/GENErate or READ PSF). Likewise, coordinates for all the atoms in the system must be defined before the functions to build the simulation box (CRYSTal) and setup images are called when setting up the periodic boundary conditions.

Running Dynamics using pyCHARMM

In CHARMM, the DYNAmic command is used to run molecular dynamics. In pyCHARMM, to do the same, an object of class `DynamicsScript` must be invoked and then the object’s member function `run()` must be called. An illustrative example in Figure 3 shows how the CHARMM DYNAmic command corresponds to the use of an instance of `DynamicsScript`.

Figure 3:

Configuring and performing a molecular dynamics run using the ‘DynamicsScript’ class in pyCHARMM. The correspondence with the DYNAmic command in CHARMM in terms of the use of command keywords as function arguments to instantiate an object of the class is shown and the presence of different categories of run parameters is illustrated. In Figure S1, the use of Python dictionaries for the same purpose is shown.

The example shows the use of function arguments used to instantiate the object. These arguments correspond exactly to the keywords that accompany the DYNAmic command in CHARMM. For example, the keyword “NSTEP”, which is used for the number of steps of integration, is supplied as a function argument by the same name (lower cased). Likewise, these function arguments can be used to specify the frequency-spec parameters (e.g., frequency of updating non-bonded lists), temperature-spec parameters (e.g., temperature and pressure conditions), unit-spec parameters (e.g., I/O channels) and options-spec parameters (e.g., method of velocity assignment) for the run. A complete list of keywords accompanying the DYNAmic command, with detailed documentation for each of the keywords, can be found at https://academiccharmm.org/documentation/version/c47b1/dynamc. One should also note that there are certain keywords as components of the DYNAmic command which do not have an associated value but whose presence in the command dictates their use. For example, the keyword “START” in the command instructs CHARMM to initiate a new dynamics run as opposed to extending a previous run (done using the RESTART keyword instead). To use them in pyCHARMM, the function argument (of the same name as the keyword) should be supplied with a ‘True’ or ‘False’ value to achieve the equivalent effect, e.g., ‘start’ = True. Conveniently, pyCHARMM also accommodates the use a Python dictionary with the aforementioned parameters instead of/in conjunction with the function arguments (Figure S1).

Of added note is the fact that the ‘DynamicsScript’ class is derived from the ‘CommandScript’ base class in pyCHARMM. Other derivatives are the ‘NonBondedScript’ and ‘UpdateNonBondedScript’. Likewise, they can be instantiated in the same way where the command keywords can be provided as function arguments or Python dictionaries or both. Then a member function ‘run()’ executes the associated action. In Figure 2, the use of ‘NonBondedScript’ class is shown.

pyCHARMM Script Factory

The ‘script_factory’ function in the pyCHARMM module gives users a convenient way to run any CHARMM command like they would when running CHARMM. This feature allows them to execute CHARMM commands that, at present, do not have a corresponding pyCHARMM function. The function takes a string as the first argument, which must correspond to a CHARMM command, and returns an object of the ‘CommandScript’ class. Subsequently, an object of the newly minted class can be instantiated while simultaneously providing arguments for the CHARMM command as function arguments or as keys in a Python dictionary. These arguments, akin to the instantiation of the DynamicsScript class object mentioned above, must correspond to the keywords that accompany the command for which the class was created. Note that keywords, whose presence only directs CHARMM to invoke or revoke specific operations of that command, must be passed with a True or False value as opposed to keywords expected to be accompanied by a value, which must be passed as an argument along with that value. As a child of the CommandScript base class, the returned class has a ‘run()’ method which can be called to execute the command. Table 1 presents an example usage of the script_factory function to run the ‘SKIPenergy’ command in CHARMM, which directs the ‘ENERgy’ command to selectively exclude or include terms when calculating and printing out energy values.

Table 1:

Example usage of the script_factory function to execute a CHARMM command without a corresponding pyCHARMM function.

SKIPenergy – EXCL BOND ANGL DIHE

import pycharmm NewSkipClass = pycharmm.script_factory(‘SKIPenergy’) my_skip = NewSkipClass(excl = “bond angl dihe”) my_skip.run()

The ‘script_factory’ function and the ‘charmm_script’ function in the lingo.py module are essentially the same. But whereas the latter would have to be fully written every time a certain command is called (for example in a loop), the class returned by ‘script_factory’ associated with that command can be used repeatedly and more conveniently to do the same.

Preserving and Extending Parallelization

CHARMM has multiple accelerated platform kernels for molecular dynamics simulations and related modeling tasks, such as the CHARMM/OpenMM interface, CHARMM/DOMDEC⁵² and CHARMM/BLaDE⁵³. They can all be accessed in pyCHARMM to run individual simulations on CPU and/or GPU hardware. In addition, the Python package mpi4py^{54, 55} can be used to run multiple simulations simultaneously, with flexible distribution of work across parallel processors enabling loosely-coupled parallelism via MPI. These two levels of parallelization can lead to significant speed-ups at par with CHARMM. However, tightly coupled MPI parallelism, as used in large parallel DOMDEC simulations, is not currently accessible in pyCHARMM.

Python Integrated Workflows Facilitate CHARMM-based Simulations in pyCHARMM

A key advantage of pyCHARMM is the ready integration with a broad range of Python functionality. This may include existing Python-based toolkits for preparing initial structures for molecular modeling and simulations (e.g., RDKit,⁵⁶ PROPKA,⁵⁷ Pybel,⁵⁸ and PDB2PQR^{59, 60}), analysis of molecular dynamics simulations, such as MDAnalysis,^{61, 62} and MDTraj,⁶³ and visualization of molecular systems and trajectories, including VMD-Python,⁶⁴ PyMOL, py3Dmol and NGLView.⁶⁵ On one hand, users could prepare a system using a single Python script and closely monitor the changes made during the process, for example, in a Python-friendly environment like Jupyter Notebooks.⁶⁶ This makes pyCHARMM a powerful tool for beginners to learn molecular modeling and simulation. On the other hand, it allows for easy implementation of various pipelines using pyCHARMM and even enables end-to-end application in some cases. For instance, by combining pyCHARMM with free energy calculation tools like FastMBAR⁶⁷ or pymbar,⁶⁸ one can implement a pipeline to rapidly compute absolute solvation free energies of small molecules using the MBAR/TI approach (see Figure 4 and AbsoluteSolvation on the GitHub site pyCHARMM-Workshop). Here, multiple molecular dynamics simulations need to be performed at various λ values for a given molecule. Then, potential energies are computed for each trajectory under perturbed thermodynamic states (i.e., with different λvalues), which are used in FastMBAR,⁶⁷ a Python solver for large scale MBAR equations, for free energy calculations. Due to the ready integration of pyCHARMM with FastMBAR and other Python modules such as numpy⁶⁹ and pandas,⁷⁰ simulation and analysis can be performed without exiting the Python environment, and this pipeline allows for end-to-end prediction of absolute solvation free energy of a given small molecule. This is illustrated in a simple example Jupyter Notebook in the GitHub repository noted above. The results of running a set of such calculations on a subset of the FreeSolv database⁷¹ using the CGENFF force field and program are shown in Figure 4B, where we illustrate application of the integrated workflow of such calculations using pyCHARMM. Similarly, we can perform high-throughput multisite λ-dynamics (MSλD) simulations⁷² using pyCHARMM to calculate relative binding free energies for multiple small molecules to a target protein. In this case, the Python tool msld_py_prep⁷³ may be utilized to identify the maximum common substructure of the set of small molecules, followed by charge renormalization. The adaptive landscape flattening (ALF) algorithm,⁷⁴ which is available as a series of Python scripts, may be used to flatten the free energy landscapes in the alchemical space, thus enhancing sampling. By integrating msld_py_prep and ALF with pyCHARMM using Python scripts it becomes much easier to perform such MSλD simulations, allowing one to compute the relative free energies of many molecules in a single simulation.

Figure 4:

(a) Illustration of the workflow in the absolute solvation free energy calculation pipeline. Based on the thermodynamic cycle, the absolute solvation free energy is obtained from the difference between ΔG_vaccum and ΔG_water, i.e., the free energy change of molecule annihilation in vacuum and water, respectively. To compute ΔG_vaccum and ΔG_water, multiple molecular dynamics simulations are performed at different λ values and potential energies are computed for each trajectory under perturbed thermodynamic states. These simulations and energy calculations can be executed in parallel to reduce the overall wall-time. Finally, FastMBAR is utilized to calculate the free energy difference between different alchemical states. (b) The absolute solvation free energies of 206 representative molecules from the FreeSolv database⁷¹ obtained using a protocol written in pyCHARMM based on the examples noted above is compared with their experimental values. The dashed line denotes the y=x line. Representative molecules were obtained by sampling from 50 functional fingerprint clusters into which all 642 molecules of the FreeSolv database was partitioned. Individual molecules were parameterized with CGenFF force field and program.^{75, 76} A representative example of this workflow is included in the GitHub repository as noted above. A detailed spreadsheet containing the molecules SMILES strings, the computed free energies and the experimental free energies taken from the FreeSolv database⁷¹ are included in the SI.

Although the original CHARMM scripting could also be used to develop complex workflows, preparing such scripts can be daunting for researchers who have little experience in molecular simulation and modeling. For example, to perform rigid docking with the CDOCKER module in CHARMM,^{77, 78} the CHARMM script contains more than 400 lines for grid generation, ligand initial placement, i.e., random translation and rotation from the pocket center, hundreds of docking trials with the simulated annealing algorithm, clustering and sorting of docked poses, and energy minimization with explicit all-atom representations. For flexible CDOCKER,⁷⁹ additional scripting is needed to select flexible side chains of the receptor, and to use the genetic algorithm to search for optimal docking poses. With pyCHARMM, these complex workflows have been compiled into a single Python module (pycharmm.cdocker) and standard docking calculation can be performed through a single pyCHARMM command (see Figure 5 and CDOCKER_WYu on the GitHub site pyCHARMM-Workshop). This greatly simplifies the usage of CDOCKER in CHARMM and is anticipated to enhance its accessibility and utility for a larger community. Also, pyCHARMM CDOCKER reduces I/O, which leads to reduced wall-time for a given docking trial. Therefore, more extensive searching can be performed to further improve the docking accuracy.⁸⁰

Figure 5:

Illustration of pyCHARMM CDOCKER. These complex workflows have been compiled into a single Python module (pycharmm.cdocker) and standard docking calculation can be performed through one-line of Python code. In this example, a ligand has been docked at a binding site after CDOCKER searched a cubic volume of edge length of 25.762 Å, centered at (12.33 Å, 33.48 Å, 19.70 Å). See the GitHub site pyCHARMM-Workshop for complete examples of rigid receptor - flexible ligand CDOCKER and flexible CDOCKER.

Another powerful feature in CHARMM is the ability of augmenting CHARMM forces and energies from user-defined energy terms in molecular modeling applications, e.g., molecular dynamics simulations, minimization, etc. With pyCHARMM, we believe that it becomes exceptionally easy to use this feature, for instance, in enhanced sampling techniques where novel, custom biasing potentials need to be incorporated, or in simulations with machine learning based force fields. In the SI (see NeuralNetExample on the GitHub site pyCHARMM-Workshop), we illustrate a simple example of using the TorchANI force field⁵¹ in pyCHARMM to examine the potential energy as a function of the dihedral angle of butane. TorchANI is a Python implementation of the ANI neural network potentials based on PyTorch, which provides accurate energies and forces for organic molecules at the QM level. With a concise pyCHARMM script, one can set up the TorchANI model and incorporate it into CHARMM calculations through the user-defined energy term. Such extensibility, customization and user-friendliness of pyCHARMM may dramatically simplify the setup of simulations with novel potential energy functions. For example, mixed machine-learning/empirical energy functions have been used in reactive molecular dynamics simulations to study ligand binding to proteins, which can carry out the necessary sampling to reach relevant time scales that were impossible with QM/MM approaches.^{81, 82} Also, hybrid machine learning/molecular mechanics potentials have shown to be highly accurate in relative binding free energy calculations.⁸³ With pyCHARMM, such simulations may be more accessible to the scientific community.

As discussed in the previous section, pyCHARMM preserves and even extends the parallel capabilities of CHARMM. A particularly useful feature is in the case of loosely coupled parallelism through the Python module mpi4py.^{54, 55} For instance, in the pipeline for absolute solvation free energy calculations as mentioned above (see Figure 4 and AbsoluteSolvation on the GitHub site pyCHARMM-Workshop for more details), mpi4py is utilized to run multiple simulations at different λ windows simultaneously, with flexible distribution of work across parallel processors (GPUs in this instance). This greatly reduces the wall time of end-to-end prediction of free energies. Similar parallelization schemes can be realized in other complex workflows as well, such as the string method for path optimization,^84–87 replica exchange,^{88, 89} umbrella sampling,⁹⁰ weighted ensemble,^91–93 and even machine-learning based enhanced sampling methods like diffusion-map-directed molecular dynamics simulations,^94–96 For example, here we provide an implementation of the string method using harmonic Fourier beads (HFB)⁸⁵ to find the optimal path between two metastable states of an alanine dipeptide (see Figure 6 and Aladipeptide_HFBString_MPI on the GitHub site pyCHARMM-Workshop). In the space of a set of collective variables, which are usually Cartesian coordinates of selected atoms, multiple beads (i.e., conformations of the system) are equally distributed along the string. During each cycle of path optimization, all beads evolve independently, using either energy minimization (to find the minimum energy path) or molecular dynamics simulation (to find the minimum free energy path). Such a path evolution procedure can be easily parallelized through mpi4py, by distributing the beads across multiple processors. After this, information from all beads is gathered and the path is updated through the HFB interpolator. Similarly, for replica exchange simulations, where multiple copies of the same system (i.e., replicas) are simulated under different thermodynamic states and they are exchanged periodically based on the Metropolis criterion, these simulations can run in parallel using mpi4py to allocate resources for each replica and to gather information from all replicas to determine how exchange is attempted and whether an exchange should be accepted (see ReplicaExchangeExample on the GitHub site pyCHARMM-Workshop for details). Besides speeding up the overall calculations in these complex workflows, another great advantage of such loosely coupled parallelization through mpi4py is that it allows researchers to modify the parallel aspects of the workflow without having to change the source code of CHARMM. Thus, pyCHARMM enables prototyping new methodological ideas in a facile manner.

Figure 6:

Demonstration of the string method applied to determine the minimum energy path between two metastable states of an alanine dipeptide in vacuum using the harmonic Fourier beads method.⁸⁵ The initial path is shown in red and the path after 2000 iterations is shown in black. See the GitHub site pyCHARMM-Workshop for a complete example.

Conclusion

In this paper, we have presented a novel Python-based instantiation of CHARMM, pyCHARMM, as well as the Python bindings, functions and modules that complement and extend the extensive set of modeling tools and methods already available in CHARMM. All of the CHARMM commands are available in pyCHARMM, either as direct Python bindings or through the CHARMM command interpreter module lingo.py. This allows users to take advantage of utilizing the wide range and distribution of CHARMM scripts as they begin learning to program their molecular modeling applications in pyCHARMM. Moreover, due to its ready integration with other Python-based visualization toolkits such as NGLView or py3Dmol, users could closely monitor the changes made at each step, especially within a Python-friendly environment like Jupyter Notebooks. Therefore, we believe that pyCHARMM will be an optimal platform for users to learn molecular modeling and simulation. With pyCHARMM new methods can become immediately available to the larger community through repositories of pyCHARMM scripts and Jupyter Notebooks. For instance, the complex workflow of rigid and flexible docking through CDOCKER has been compiled into a single Python module (pycharmm.cdocker) and standard docking calculations can be performed with a one line Python call. This makes pyCHARMM CDOCKER more user-friendly and will enhance its accessibility and utility for a larger community.

pyCHARMM should also serve as a robust platform for the development of comprehensive and complex workflows for researchers with more experience in molecular simulation and modeling. As a complete and programmable package in the Python framework, pyCHARMM can be readily integrated with other Python functions and toolkits. This allows for easy implementation of various pipelines, such as alchemical free energy calculations using MBAR/TI approaches or high-throughput free energy calculations with MSλD. Another powerful feature in pyCHARMM is the ability to augment CHARMM forces and energies with user-defined energy terms, especially machine learning based force fields. This may be particularly useful in developing novel enhanced sampling methods as well as in simulations with hybrid machine learning/molecular mechanics force fields. pyCHARMM also provides a straightforward means of implementing parallel calculations. Moreover, multiple accelerated platform kernels, such as the CHARMM/OpenMM interface, CHARMM/DOMDEC and CHARMM/BLaDE, are available in pyCHARMM. Loosely coupled parallelization achieved through the Python module mpi4py, for instance, in alchemical free energy calculations, string path optimization calculations, and replica exchange significantly enhance the configurability and facile implementation of such calculations. This not only speeds up the overall calculations in these complex workflows, but also makes modification of existing workflows exceptionally easy. Taken all together, pyCHARMM permits the general and flexible control of complicated simulation protocols and facilitates the prototyping of new methodological ideas.

We finally summarize by noting that CHARMM and subsequently pyCHARMM are available free of charge to non-profit laboratories through the established CHARMM licensed distribution at www.academiccharmm.org. This distribution provides full access to all sources needed to install pyCHARMM. In addition, we have developed an evolving GitHub site pyCHARMM-Workshop (https://github.com/clbrooksiii/pyCHARMM-Workshop) that includes many of the examples discussed in this paper as Jupyter Notebooks or python scripts. With the work we present here it is our intention to provide a Python-based platform for molecular modeling and simulation that brings the extensive development of methods and techniques from CHARMM to the broad community of novice and expert molecular modelers.

Data Availability

All data, examples, documentation files and tutorial files that are described and discussed here are available in the GitHub repository (https://github.com/clbrooksiii/pyCHARMM-Workshop). The full source and documentation for CHARMM and pyCHARMM are licensed and available free of charge to non-profit and academic laboratories at https://academiccharmm.org/program. The release version of CHARMM/pyCHARMM described here corresponds to c47b2.