2021-03-17 Mitchell/Wagner Meeting notes

Dev docs questions

• Is existing ParameterHandler description correct?

  • _MAX_SUPPORTED_SECTION_VERSION not present in vdWHandler code

    • Base class specifies defaults

    • Should be min/max not max/max

  • _TAGNAME, _INFOTYPE, _KWARGS, _SCALETOL, _DEPENDENCIES not documented

    • TAGNAME needs to correspond to the “second-level”? SMIRNOFF element names (also sometimes referred to as “Section headers”, but generally meaning 'things like the word “Bonds” or “ProperTorsions”'). This is used to populate a registry of ParameterHandler classes, and as a SMIRNOFF OFFXML file is being parsed, second-level tag/element names (as strings, for example the string “Bonds”) are used to look up which kind of ParameterHandler to initialize, based on its TAGNAME.

    • INFOTYPE is used internally while a ParameterHandler is being initialized. It tells the ParameterHandler which ParameterType constructor should parse each element in its parameter list. This takes advantage of the architecture, as the __init__ function for ParameterType is very similar to a deserializer. For example, the BondHandler’s INFOTYPE is BondType. For each bond, the attributes (like k, length , smirks, id, etc) are passed as kwargs to the BondType.__init__ function.

    • KWARGS is known_kwargs, but renamed. This is the list of keyword arguments to intercept from a user’s top-level call to create_openmm_system. For example, the fractional_bond_orders_from_molecules keyword argument to create_openmm_system is actually there to carry information to BondHandler and ProperTorsionHandler. The developers guide should refer to the all-capital version (_KWARGS).

      • IT’s not actually clear that exposing this accomplished anything that inspecting the create_force methods of all registered parameterhandlers in a ForceField could do. One reverse-compatible way forward could be to inspect the create_force and postprocess_system methods if KWARGS is undefined.

    • SCALETOL is a attribute of Electrostatics, GBSA, and vdWHandlers, that is specific to their implementations. This does not need to be documented.

    • DEPENDENCIES is a list of classes of ParameterHandlers that MUST run (if present) before this one. If a ForceField does not contain a ParameterHandler that is listed as a dependency of this one, that’s OK (no error is raised). Use of DEPENDENCIES is frequently inevitable, but is generally considered to be “bad”. In a perfect world, the energy components of a system would be entirely modular and not need to know anything about each other.

    • Wherever both ParameterAttribute and IndexedParameterAttribute are mentioned, also include MappedIndexedParameterAttribute

  • Scale stuff?? - Don’t document

  • Remove additional CSS stylesheet

• Is my interpretation of ParameterType and ParameterAttribute correct?

New tasks?

• Better workflow for users to access examples (without needing to go into miniconda directories)

  • Could copy example folder(s) to current directory

  • Use the click package. Seek inspiration from openff-benchmark and openff-cli. https://github.com/openforcefield/openff-cli/

• Thar be monsters (add user warnings about PDB format): https://github.com/openforcefield/openff-toolkit/issues/704

From last time

• Examples (or taking a stab so we can start figuring out example standards)

• “Search and destroy” throughout the docs, highlighting ambiguities or poorly-written sections, and possibly attempting to fix.

  • Especially “developer docs”

    • Break up into different pages?

    • Send some parts to user guide?

    • Is the writing style meaningfully legible? Should it be wordier/less wordy? more/less technical?

• https://github.com/openforcefield/openff-toolkit/issues/755