|
| 1 | + |
| 2 | +Compiling |
| 3 | +========= |
| 4 | + |
| 5 | +Let's start with an overview of terminology.: |
| 6 | + |
| 7 | +* **Compiling**: The process of converting input in a text format, |
| 8 | + such as YAML or JSON, into OPS objects. Here we're focused on non-Python |
| 9 | + alternatives to using the standard Python interpreter to compile objects. |
| 10 | +* **Category**: The base category of object to be created (engine, CV, |
| 11 | + volume, etc.) |
| 12 | +* **Builder**: We will refer to a builder function, which creates an |
| 13 | + instance of a specific |
| 14 | + |
| 15 | +Everything is created with plugins. There are two types of plugins used in |
| 16 | +the ``compiling`` subpackage: |
| 17 | + |
| 18 | +* ``InstanceCompilerPlugin``: This is what you'll normally work with. These |
| 19 | + convert the input text to an instance of a specific OPS object (for |
| 20 | + example, an ``OpenMMEngine`` or an ``MDTrajFunctionCV``. In general, you |
| 21 | + do not create subclasses of ``InstanceCompilerPlugin`` -- there are |
| 22 | + subclasses specialized to engines (``EngineCompilerPlugin``), to CVs |
| 23 | + (``CVCompilerPlugin``), etc. You create *instances* of those subclasses. |
| 24 | + You write your builder function, and wrap in with in an instance of an |
| 25 | + ``InstanceCompilerPlugin``. |
| 26 | +* ``CategoryPlugin``: These manage the plugins associated with a given |
| 27 | + features. Contributors will almost never need to create one of these. |
| 28 | + The only case in which you would need to create one of these is if you're |
| 29 | + creating a new *category* of object, i.e., something like an engine where |
| 30 | + users will have multiple options at the command line. |
| 31 | + |
| 32 | +Other useful classes defined in the ``compiling`` subpackage include: |
| 33 | + |
| 34 | +* ``Builder``: The ``Builder`` class is a convenience for creating builder |
| 35 | + functions. It takes either a callable or a string as input, where a string |
| 36 | + is treated as a path to an object to import at runtime. It also allows |
| 37 | + takes parameters ``remapper`` and ``after_build``, which are callables |
| 38 | + that act on the input dictionary before object creation (``remapper``) and |
| 39 | + on the created object after object creations (``after_build``). |
| 40 | +* ``CategoryCompiler``: This class manages plugins for a given category, as |
| 41 | + well as tracking named objects of that type. These are created |
| 42 | + automatically when plugins are registered; users do not need to create |
| 43 | + these. |
0 commit comments