atomate2 / OpenMM OPLS-AA Enhancements

[shehan807]

Summary

This PR resolves the first two enhancements proposed in Issue #1102:

• Feature 1: Implements the correct geometric combination rules for OPLS MD simulations via opls_lj()

I've changed create_system_from_xml to create_ff_from_xml in src/atomate2/openmm/jobs/generate.py. Why? The OPLS geometric combination rules have two requirements, (1) a CustomNonbondedForce in OpenMM that combines the sigma and eps parameters geometrically, and (2) the coulomb14scale and lj14scale attributes of the ForceField are both 0.5. The latter was enough justification for raising an error if not the case--to do so, the ForceField object would need to be accessible in generate_openmm_interchange (instead of adding unsuitable arguments to create_system_from_xml). Originally, create_system_from_xml created both the ForceField and System within the same function; now, system and ff are separate variables in generate_openmm_interchange.

• Feature 2: Allows users to create OPLS forcefield files via generate_opls_xml() via LigParGen and BOSS source code directly. To do so, users would need to follow the steps in the docs from this fork.

Currently, generate_opls_xml is only functional so long as the user has a local installation of Docker and created a private (for now, pending approval for pushing to public registries approval received to save on public registries) image of LigParGen. The documentation is provided to completion in docs/user/codes/openmm.md.

EDIT: We've received written approval from Dr. William Jorgensen to host the LigParGen image on a public registry, i.e., the user no longer has to build this themself.

• Feature 3: All changes from Generalize download_opls_xml Function #1054 have been merged into this fork (i.e., extending the download_opls_xml to handle charges, number of optimization iterations, and charge method).

Additional dependencies introduced

• defusedxml, resolves ruff failures for safely loading XML files, e.g.,

• textwrap, enables easier text wrapping of long warnings/errors printed for the user, e.g.,

Checklist

• Code is in the standard Python style.
  The easiest way to handle this is to run the following in the correct sequence on
  your local machine. Start with running ruff and ruff format on your new code. This will
  automatically reformat your code to PEP8 conventions and fix many linting issues.
• Doc strings have been added in the Numpy docstring format.
  Run ruff on your code.
• Type annotations are highly encouraged. Run mypy to
  type check your code.
• Tests have been added for any new functionality or bug fixes.
• All linting and tests pass.

CC'ing @utf, @orionarcher

[orionarcher]

Couple comments but generally looks good!

[orionarcher]

Do we need defusedxml in particular? Best to avoid adding a dependency if possible

[shehan807]

ruff gave me the following error for ET.parse,

S314 Using `xml` to parse untrusted data is known to be vulnerable to XML attacks; use `defusedxml` equivalents

I now see that # noqa: S314 was there in the original version to suppress this error, so I've updated the try/except statement, now without defusedxml. I also removed the textwrap dependency.

[orionarcher]

tags should just be metadata, not core logic. You can add another mixing related kwarg as needed

[shehan807]

Good point--I've replaced this behavior with an ff_kwargs argument to generate_openmm_interchange.

[orionarcher]

can you document what params are allowed?

[shehan807]

Done.

[orionarcher]

-> test_create_ff_from_xml

[orionarcher]

@janosh or @utf could you get the tests running here?

[shehan807]

@janosh all pre-commit/pytests are working on my end as of my last commit, could you try running the tests again? Thanks @orionarcher for the comments!

[shehan807]

@janosh The last failed test is due to an environment variable dependence introduced by the generate_opls_xml function. The function requires the user to follow the OPLS docs to create a CONTAINER_SOFTWARE and LPG_IMAGE_NAME environment variable:

export LPG_IMAGE_NAME="USERNAME/ligpargen:latest"
export CONTAINER_SOFTWARE="podman-hpc" # e.g.

Based on what I've observed from the VASP/AIMS tests, I just updated test_generate_opls_xml so it monkeypatches environment variables. The new tests are now broken up into test_generate_opls_xml_no_container and test_generate_opls_xml_success. The latter is skipped since, even if the env variables were set, it would fail because success depends on whether podman-hpc or docker are available.