Skip to content

Commit 3daa542

Browse files
committed
add docs/compiling.rst
1 parent 0318227 commit 3daa542

1 file changed

Lines changed: 43 additions & 0 deletions

File tree

‎docs/compiling.rst‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
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

Comments
 (0)