GROMACS

To address issues #3130 and #3136, it is necessary to revise both the way API input and output data is described and the way users interact with function arguments.

Background¶

While a gmxapi typing system and C++ data model was delayed, we adopted a combination of native Python types and trivial custom types to define operation inputs, provide static type hinting for users, drive the generation of wrapper code, perform input compatibility checks, and inform implicit handling of data shape transformations. Current software state and works in progress include scatter() and gather() helper functions, NDArray and EnsembleDataSource classes, and incomplete static type hinting.

To clarify a snapshot of syntax and semantics from which to build from, a series of commits under review revises the above-mentioned entities and, in many cases, requires Python iterables to be explicitly wrapped with scatter(), gather(), or ndarray() to clarify user intent for the API. These interface revisions may cause confusion to users, though.

This issue asserts that we can preempt a harmfully confusing interim interface with a user interface that, while imperfect, allows us to separate the underlying issues and provide consistent semantics moving forward.

Proposal¶

Inputs to gmxapi operations must be references to gmxapi objects. We can refine heuristics for implicit conversions in the future, but the immediate fix will be to require native Python data to be explicitly converted to a gmxapi data object before using as input to a gmxapi operation. The helper function for creating such an object consolidates the user interface for defining data shape and parallelizability.

We can minimize some dependency on updated type hinting machinery by first addressing #3140 and converting the existing function-annotation-based operation input expression.

Syntax¶

A single helper function can return an object interpretable by the API for a Python literal or object provided by the caller. Constraints on the interpretation of the data can be expressed with optional key word arguments. Constraints include data shape, data type, parallelizability and allowable conversions.

We can provide additional helper functions for basic transformations, if necessary, but a function name containing "as", like gmxapi.as_data(), implies the common convention that conversions may be performed on the input object.