Molecular Dynamics Core Package Release Notes

v2.5.1 February 2025

General Notice

Various aspects of Orion MD Core have been refactored and improved significantly in this version. Please note that some changes are unfortunately API-breaking, which may affect existing implementations. These changes are explicitly marked as (API-breaking) in the release notes below.

Cube Updates

The Solvation Cube has been updated as follows:
- The default salt concentration has been increased to 150 mM from 50 mM.
- The box size for small molecule is now determined considering the largest small molecule conformation along Omega sampling.
- A new md_cutoff_distance cube parameter has been defined to ensure that the minimum image convention is always enforced along MD runs.
- Ions in solutions are now placed far from the solute.
- A new min_number_of_salt cube parameter has been defined to ensure that the selected minimum number of ions are always present in solution. This parameter has been introduced to ensure future charge corrections change ligand mutations along RBFE calculations.
(API-breaking) The Collection Setting Cube has been refactored to use a new parameter, collection_fields, to specify which collection will be set on the input record. Additionally, a new string parameter, operation, has been introduced to define the action to perform on the collection. Supported values for operation are "open", "close", and "create".

Major Improvements

Support has been added for storing the bond orders in trajectories generated by the MD cubes using OpenMM as the engine. Bond orders can be accessed in output trajectory files as follows:

import mdtraj
# NOTE: mdcore must be imported for bond orders to be recognized by mdtraj,
# even if mdcore is not explicitly used
import orionmdcore

# load the trajectory from the last stage
traj_file = md_record.get_state_trajectory()
traj = mdtraj.load(traj_file)

# check if bond orders are present
for bond in traj.top.bonds:
    assert bond.order is not None

MDDataRecord has been improved in the following ways:
- MDDataRecord now internally uses the link, as opposed to integer IDs, to reference MD data stored as Orion resources (e.g., shards and files). ID fields from old records are automatically upgraded to links once MDDataRecord is initialized.
- MDDataRecord.get_value and MDDataRecord.set_value now return/expect Orion resources instead of links when dealing with link-type fields. For example:
```
# generic record
link_dict = record.get_value(MDFields.mddata)  # returns a link dict referencing the shard
link = APISession.get_link(link_dict)
shard = link.get_shard()

record.set_value(MDFields.mddata, link)  # sets with a link referencing the shard

# MDDataRecord
md_record = MDDataRecord(record)
shard = md_record.get_value(MDFields.mddata)  # returns the shard
md_record.set_value(MDFields.mddata, shard)  # sets with the shard
```
- Related utility functions and tools, including mdocli, have been refactored to support links stored on MDDataRecord.
- A new function, get_stage, has been added to MDDataRecord that can be used to retrieve MD stages by either stage index or name.
- MDDataRecord.get_stages and other MD stage getters now return an MDDataRecord instead of a generic record.
- (API-breaking) The input parameter of MDDataRecord.get_stage_by_name, MDDataRecord.has_stage_name, and MDDataRecord.delete_stage_by_name has been renamed from stg_name to name for improved clarity and simplicity. Additionally, the parameter can now be provided as either a positional or keyword argument. For example:
```
stage = md_record.get_stage_by_name("production")  # stage name as positional argument
stage = md_record.get_stage_by_name(name="production")  # stage name as keyword argument
```
- (API-breaking) The input parameter of the several member functions of MDDataRecord related to getting and setting the MD stage data has been changed such that the user can provide either the name or the index of the stage. The name of the parameter has been changed from stg_name to stage_id to reflect this new capability. Additionally, the parameter can now be provided as either a positional or keyword argument. For example:
```
traj_file = md_record.get_stage_trajectory("production")  # stage name as positional argument
traj_file = md_record.get_stage_trajectory(stage_id="production")  # stage name as keyword argument
traj_file = md_record.get_stage_trajectory(-1)  # stage index as positional argument
traj_file = md_record.get_stage_trajectory(stage_id=-1)  # stage index as keyword argument
```
Atoms in all components except for ligand and other_ligands are now reordered in MDComponents to enforce and satisfy the requirements for GROMACS topology. This should allow systems that were previously failing in GROMACS to be successfully simulated.
A new property, designunit, has been added to MDComponents for converting and retrieving an OEDesignUnit object from MDComponents.

Minor Improvements

Package dependencies have been updated to include the latest versions.
The use_gpu_cpu option in the OpenMMSimulations class has been renamed to "use_gpu" and changed to take Boolean values.
A precision option has been added to the OpenMMSimulations class, allowing users to specify the numerical precision for simulations when using the GPU. Supported values for this option are "single", "double", "mixed", and "auto". If precision="auto", the simulation defaults to mixed precision when available; otherwise, it falls back to single precision. The default value is "mixed", which requires mixed precision (i.e., fails when mixed precision is unavailable).

Bug Fixes

A rounding error has been fixed when calculating the total number of steps in MD runs.
An issue has been fixed that can lead to memory leaks when deserializing MDComponents from a record.
A bug has been fixed in the Delete MD Recovery Cube that could cause a deadlock.
An issue has been fixed where no record is emitted from NVT/NPT cubes when the simulation runtime is zero.
Various smaller bugs have been fixed.