diff --git a/docs/source/background/architecture.rst b/docs/source/background/architecture.rst index 2405b1d08..2e7c3ab95 100644 --- a/docs/source/background/architecture.rst +++ b/docs/source/background/architecture.rst @@ -31,7 +31,7 @@ on how this architecture addresses the considerations raised in the (including its major dependency). The right shows how PluginPlay is fed contents, *i.e.*, by ingesting plugins containing modules. -Fig. :ref:`fig_pp_arch_full` shows the conceptual architecture of PluginPlay. +:numref:`fig_pp_arch_full` shows the conceptual architecture of PluginPlay. PluginPlay itself is built on top of the runtime system implemented by `ParallelZone `__. Internally PluginPlay is made up of four components: @@ -46,7 +46,7 @@ Internally PluginPlay is made up of four components: #. **Call Graph**. This component contains a runtime representation of the program's control flow. -Fig. :ref:`fig_pp_arch_full` also tries to make the point that PluginPlay is +:numref:`fig_pp_arch_full` also tries to make the point that PluginPlay is just a framework, *i.e.*, a piece of software designed to facilitate writing other software by serving as a "template" for the program. PluginPlay does not contain any scientific functionality; scientific functionality must be supplied diff --git a/docs/source/background/statement_of_need.rst b/docs/source/background/statement_of_need.rst index 6f18f78ab..2dfa20fee 100644 --- a/docs/source/background/statement_of_need.rst +++ b/docs/source/background/statement_of_need.rst @@ -29,7 +29,7 @@ piece of code: Unfortunately, simply having a heap of modules does not equate to having research capable software. This is because you still need to "wire" the modules -together to form a program. Fig. :numref:`fig_pp_wire_modules` illustrate this +together to form a program. :numref:`fig_pp_wire_modules` illustrate this point pictorially. .. _fig_pp_wire_modules: diff --git a/docs/source/developer/design/call_graph.rst b/docs/source/developer/design/call_graph.rst index 9a33a6bbb..ec06940df 100644 --- a/docs/source/developer/design/call_graph.rst +++ b/docs/source/developer/design/call_graph.rst @@ -220,7 +220,7 @@ pieces it is now possible to describe how nodes will actually call one another. the code boundary in type-erased form. To try and make the design from the last section more intuitive consider -Fig. :numref:`fig_data_flow`. The left side shows the process of passing data +:numref:`fig_data_flow`. The left side shows the process of passing data into a :ref:`module`. This can be passing data into the first :ref:`module` in the call graph or from one :ref:`module` in the call graph to another. The first step is to type-erase the data. This is done by feeding the data through @@ -261,7 +261,7 @@ Assembling the Call Graph With a design in place to wrap algorithms in modules, and a design for how to call the modules, the last piece of the call graph component is literally assembling the call graph. As a first pass we have adopted a simple solution -depicted in Fig. :numref:`fig_assemble_call_graph`. +depicted in :numref:`fig_assemble_call_graph`. .. _fig_assemble_call_graph: @@ -277,13 +277,13 @@ depicted in Fig. :numref:`fig_assemble_call_graph`. Rather than create a literal call graph object to represent the call graph we have taken a linked list approach. When a module developer writes a module they register with PluginPlay all of their callback points. In -Fig. :numref:`fig_assemble_call_graph` the developer has registered three +:numref:`fig_assemble_call_graph` the developer has registered three callback points. To distinguish callback points within the module, each callback point is assigned a unique name (unique within the scope of the module). Here these names are ``"Callback A"``, *etc.*. In addition to the name of the callback point, PluginPlay also needs to know what :ref:`property_type` will be used for the callback. Module developers register the domain-specific -property type they will use. As noted in Fig. :numref:`fig_assemble_call_graph` +property type they will use. As noted in :numref:`fig_assemble_call_graph` the property types need not be different. These steps are written as part of developing the module (although they will actually get executed at run time). diff --git a/docs/source/developer/design/field.rst b/docs/source/developer/design/field.rst index e2928ae94..3be9178af 100644 --- a/docs/source/developer/design/field.rst +++ b/docs/source/developer/design/field.rst @@ -76,7 +76,7 @@ Field Component Design ModuleResult are responsible for respectively managing the inputs/results to/from a module and SubmoduleRequest is used to manage callback hooks. -Fig. :numref:`fig_field_design` shows the architecture of the field component. +:numref:`fig_field_design` shows the architecture of the field component. The three major components, ``ModuleInput``, ``ModuleResult``, and ``SubmoduleRequest`` correspond to three major items passed into/from modules. ``ModuleInput`` manages an input to a module (the set of inputs passed to a diff --git a/docs/source/developer/design/module.rst b/docs/source/developer/design/module.rst index aafbd7240..2b5f7a6e7 100644 --- a/docs/source/developer/design/module.rst +++ b/docs/source/developer/design/module.rst @@ -112,7 +112,7 @@ Module Usage How inputs traverse the module component. -Fig. :numref:`fig_calling_a_module` depicts the process of a user interacting, +:numref:`fig_calling_a_module` depicts the process of a user interacting, *i.e.*, calling, the module. First, the user selects the property type to run the module as. The property type defines the inputs the user must provide, and the user passes the appropriate inputs into the ``Module`` class. Inside the @@ -129,7 +129,7 @@ from the derived class through the ``ModuleBase``, ``ModulePIMPL``, and locks during the aforementioned process to avoid concurrent modifications to its state. -While not shown in Fig. :numref:`fig_calling_a_module`, memoization occurs in +While not shown in :numref:`fig_calling_a_module`, memoization occurs in the ``ModulePIMPL`` class (``ModuleBase`` is shared by all instances of the same module and, with the exception of the temporary cache, read-only). The design of the memoization process is covered in more detail diff --git a/docs/source/developer/design/module_manager.rst b/docs/source/developer/design/module_manager.rst index 84f4335c3..db9fa0dab 100644 --- a/docs/source/developer/design/module_manager.rst +++ b/docs/source/developer/design/module_manager.rst @@ -79,7 +79,7 @@ Module Manager Architecture Architecture of the module manager component. -Fig. :numref:`fig_mm_arch` shows the architecture of the module manager +:numref:`fig_mm_arch` shows the architecture of the module manager component. The user-facing :ref:`api` is codified by a ``ModuleManager`` class. Using the :ref:`pimpl` idiom, the implementation of the ``ModuleManager`` (and PluginPlay itself) is separated from the :ref:`api`. The current design @@ -108,18 +108,18 @@ Module Pool The new component here is the "Loaded Module" component, which is an associative array of loaded modules used like a :ref:`module` pool. Conceptually the main -points of this pool are summarized in Fig. :numref:`fig_mm_module_pool`. Here +points of this pool are summarized in :numref:`fig_mm_module_pool`. Here our user has loaded one module under the module key ``"Module A"`` (we'll discuss ``"Module B"`` below). Module keys are used to refer to the modules in the module pool. Each module choice has a unique key meant to facilitate referring back to a specific module. When the user loads ``"Module A"``, ``"Module A"`` is inserted into the module -pool as is. Fig. :numref:`fig_mm_module_pool` depicts ``"Module A"`` as having +pool as is. :numref:`fig_mm_module_pool` depicts ``"Module A"`` as having four, members. The values of these four members, define the default state for ``"Module A"``. If a user does not want to use ``"Module A"`` in its default state, they can create a new configuration. This is what ``"Module B"`` -represents in Fig. :numref:`fig_mm_module_pool`, *i.e.*, ``"Module B"`` is a +represents in :numref:`fig_mm_module_pool`, *i.e.*, ``"Module B"`` is a different configuration of ``"Module A"`` which differs in that the value of ``Member C`` is replaced with some new value ``Member E``. Thus configurations are stored as differences. That is to say each configuration contains a link to @@ -147,7 +147,7 @@ The current design of the module manager really only directly addresses concern two (*i.e.*, managing of :ref:`module` pool) and punts the remaining concerns. More specifically: -# Dynamic module management +#. Dynamic module management - Operations go through ``ModuleManager`` class - Different configurations handled by module pool diff --git a/docs/source/tutorials/modules/basics.rst b/docs/source/tutorials/modules/basics.rst index ad39dbe57..f15c616f5 100644 --- a/docs/source/tutorials/modules/basics.rst +++ b/docs/source/tutorials/modules/basics.rst @@ -90,7 +90,7 @@ For our ``CoulombsLaw`` module a basic constructor looks like: .. literalinclude:: ../../../../tests/python/doc_snippets/coulombslaw_force.py :language: python - :lines: 21-26 + :lines: 22-25 One particularly nice feature of PluginPlay is that it can autogenerate restructured text documentation for modules by scraping the meta-data and fields @@ -143,7 +143,7 @@ code are: .. literalinclude:: ../../../../tests/python/doc_snippets/coulombslaw_force.py :language: python - :lines: 28-31,43-44 + :lines: 27-30,42-43 The inputs to a module are type-erased. Getting them back in a usable typed form can be done automatically via template meta-programming. The details of this @@ -170,7 +170,7 @@ computing the electric field) is: .. literalinclude:: ../../../../tests/python/doc_snippets/coulombslaw_force.py :language: python - :lines: 28-44 + :lines: 27-43 Submodules ==========