Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding docs #989

Merged
merged 3 commits into from Jul 10, 2019
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
3 changes: 3 additions & 0 deletions docs/sphinx/manual.rst
Expand Up @@ -7,6 +7,8 @@

.. _manual:

.. Note: You can find rst replacement definitions in cmake/templates/conf.py.in

=======
Manual
=======
Expand Down Expand Up @@ -38,3 +40,4 @@ examples, and document the components of the system.

manual/about
manual/software_stack
manual/lra_example
4 changes: 2 additions & 2 deletions docs/sphinx/manual/about.rst
Expand Up @@ -11,7 +11,7 @@
About |phylanx|
============================

Phylanx is a distribured Machine Learning platform
Phylanx is a distributed Machine Learning platform
that aims to provide users a high level, Python interface
which delivers HPC performance. At its core Phylanx is
a general purpose system for computing large distributed
Expand All @@ -22,7 +22,7 @@ specifically to support distributed computing. The system will
decompose array computations into a predefined set of parallel
operations and employ algorithms which optimize execution and data
layout from of a user provided expression graph. Using hints from
the user as well as applicaiton logic an expression graph is
the user as well as application logic an expression graph is
created which is then passed to HPX, a distributed C++
runtime system used to schedule and execute the work on
commodity systems.
Expand Down
56 changes: 56 additions & 0 deletions docs/sphinx/manual/lra_example.rst
@@ -0,0 +1,56 @@
..
Copyright (C) 2018 Mikael Simberg
Copyright (C) 2019 Adrian Serio

Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

==============
LRA Example
==============

In this section we demonstrate using |phylanx| with the Python frontend.
In addition, power users can also interface with |phylanx| by writing
PhySL code or C++ directly. We will describe these interfaces in
following sections.

----------------------------------------
Using |phylanx| with the Python Frontend
----------------------------------------

In order to take advantage of |phylanx|, users can decorate their
Python code with Python decorators which will interpret and execute the
code block in |phylanx|. An example of this technique can be found
in the LRA (Linear Regression Algorithm) example below.

.. literalinclude:: ../../../../examples/algorithms/lra/phylanx_lra_csv_np.py
:language: python

As shown in the example above, users import |phylanx| and
encapsulate their code in a @Phylanx decorator. The NumPy
commands will additionally be converted into |phylanx| primitives
when placed in a |phylanx| decorator.
When encapsulated, the code will be transformed into AST which
represents the operations to be performed.

.. Todo: Mention command to print out PhySL

--------------------------
Using |phylanx| with PhySL
--------------------------

.. note:: This section is for power users. We encourage
our users to take advantage of the user friendly Python
Frontend. All functionality made available through this
interface is as available in our Python Frontend.

The |phylanx| AST can be directly constructed using PhySL,
or **Phy**\ lanx **S**\ pecification **L**\ anguage. This small language
allows users to compile a raw string which produces
an AST when it is compiled.

An example of using this interface can be found below:

.. literalinclude:: ../../../../examples/algorithms/lra/lra_csv.cpp
:language: cpp

36 changes: 18 additions & 18 deletions docs/sphinx/manual/software_stack.rst
Expand Up @@ -5,29 +5,29 @@
Distributed under the Boost Software License, Version 1.0. (See accompanying
file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

=======
==============
Software Stack
=======
==============

The |phylanx| framework is made up of several distinct
layers as illustrated in Figure 1.

.. figure:: images/phylanx_overview.png
:width: 200px
:width: 315px
:align: center
:height: 100px
:height: 264px
:alt: alternate text
:figclass: align-center

Figure 1. Overview of the |phylanx| toolkit.

In this portion of the manuel we discuss
In this portion of the manual we discuss
the external libraries |phylanx| depends on
and the layers of the software stack.

-------
------------------
External Libraries
-------
------------------

^^^^^^^
HPX
Expand Down Expand Up @@ -67,9 +67,9 @@ a policy engine. To learn more about the project,
please refer to the
`APEX repository <https://github.com/khuck/xpress-apex>`_

-------
--------
Frontend
-------
--------

The Phylanx frontend provides two essential functionalities:

Expand Down Expand Up @@ -112,7 +112,7 @@ function that will be run by an HPX task during evaluation, and (2) it can be
used for debugging and analyzing purposes for developers interested in custom
optimizations.

The compiled kernel is cached and can be be invoked directly in Python or in
The compiled kernel is cached and can be invoked directly in Python or in
other kernels.

2. **Data Management** - Phylanx's data structures rely on
Expand All @@ -128,9 +128,9 @@ take advantage of Python buffer protocol through
the pybind11 library. Figure~\ref{fig:phylanxarch} shows how
Phylanx manages interactions with external libraries.

-------
--------------
Execution Tree
-------
--------------

After the transformation phase, the frontend passes
the generated AST to the Phylanx compiler to construct
Expand Down Expand Up @@ -162,7 +162,7 @@ result of the kernel. In the evaluation function,
the root node will call the evaluation function of
all of its children and those primitives will call the
evaluation functions of their children. This process
will continue until the the leaf nodes have been
will continue until the leaf nodes have been
reached where the primitives evaluation functions
do not depend on other primitives to be resolved
(e.g. a primitive which is a constant, a primitive
Expand All @@ -182,9 +182,9 @@ its execution, the result of the entire tree
is then ready to be consumed by the calling
function.

-------
---------------
Instrumentation
-------
---------------

Application performance analysis is a critical part
of developing a parallel application. Phylanx
Expand All @@ -200,9 +200,9 @@ directly used by the users or fed
into APEX for adaptive load balancing. The data can also
be used by the visualization tools described in the next section.

-------
Viusualization Tools
-------
--------------------
Visualization Tools
--------------------

Embedding annotations and measurements for
visualizations and performance
Expand Down