Tweak formatting for readability and add more cross references. Add example... (3b3e963a) · Commits · Cianciosa, Mark / graph_framework

graph_docs/compiling.dox

+35 −20

Original line number	Diff line number	Diff line
		@@ -7,6 +7,7 @@
		* This page details the <a href="http://www.cmake.org">cmake</a> based build
		* system.
		*
		* <hr>
		* @section build_system_user User Guide
		* The following section is for users of framework.
		*
		@@ -68,14 +69,22 @@
		* are various options for configuing LLVM and can be ignored. The important
		* options are listed below.
		*
		* * <tt>CMAKE_BUILD_TYPE</tt> Switch between <tt>Release</tt>, <tt>Debug</tt>, <tt>MinSizeRel</tt>, <tt>RelWithDebInfo</tt>
		* * <tt>USE_VERBOSE</tt> Show verbose information about compute kernels.
		* * <tt>BUILD_C_BINDING</tt> Generate the C langauge interface.
		* * <tt>BUILD_Fortran_BINDING</tt> Generate the Fortran language interface.
		* * <tt>USE_METAL</tt> Enable the <a href="https://developer.apple.com/metal/">Metal</a> backend (macOS only).
		* * <tt>USE_CUDA</tt> Enable the <a href="https://developer.nvidia.com/cuda-zone">Cuda</a> backend (Linux only).
		* * <tt>USE_HIP</tt> Enable the <a href="https://www.amd.com/en/products/software/rocm.html">Hip</a> backend (Linux only, Hip branch).
		* * <tt>USE_SSH</tt> Use ssh for git instead of html.
		* <table>
		* <caption id="build_system_user_cmake_opts">Build options for users.</caption>
		* <tr><th>Option <th>Discrption
		* <tr><td><tt>CMAKE_BUILD_TYPE</tt> <td>Switch between
		* * <tt>Release</tt>
		* * <tt>Debug</tt>
		* * <tt>MinSizeRel</tt>
		* * <tt>RelWithDebInfo</tt>
		* <tr><td><tt>USE_VERBOSE</tt> <td>Show verbose information about compute kernels.
		* <tr><td><tt>BUILD_C_BINDING</tt> <td>Generate the C langauge interface.
		* <tr><td><tt>BUILD_Fortran_BINDING</tt><td>Generate the Fortran language interface.
		* <tr><td><tt>USE_METAL</tt> <td>Enable the <a href="https://developer.apple.com/metal/">Metal</a> backend (macOS only).
		* <tr><td><tt>USE_CUDA</tt> <td>Enable the <a href="https://developer.nvidia.com/cuda-zone">Cuda</a> backend (Linux only).
		* <tr><td><tt>USE_HIP</tt> <td>Enable the <a href="https://www.amd.com/en/products/software/rocm.html">Hip</a> backend (Linux only, Hip branch).
		* <tr><td><tt>USE_SSH</tt> <td>Use ssh for git instead of html.
		* </table>
		*
		* <b>NOTE:</b>macOS uses will need to change the default option for
		* <tt>CMAKE_CXX_COMPILER</tt> to <tt>clang++</tt>. This is due to the way the
		@@ -127,6 +136,7 @@
		* Like the parallel build the <tt>-j<i>num_processes</i></tt> option determines
		* number of parallel instances to run.
		*
		* <hr>
		* @section build_system_dev Developer Guide
		* This section covers information for developers of the framework itself.
		*
		@@ -194,16 +204,21 @@
		* that can be enabled.
		*
		* @subsubsection build_system_dev_options Build system Options
		* * <tt>USE_PCH</tt> Use precomiled headers during computation. Most users should keep this on.
		* * <tt>SAVE_KERNEL_SOURCE</tt> Option to dump the generated compute kernel source code to disk.
		* * <tt>USE_INPUT_CACHE</tt> Option to cache registers for the kernel arguments.
		* * <tt>USE_CONSTANT_CACHE</tt> Option to use registers to cache constant values otherwise constanst are inlined.
		* * <tt>SHOW_USE_COUNT</tt> Generates information on the number of times a register is used.
		* * <tt>USE_INDEX_CACHE</tt> Option to use registers to cache array indicies.
		* * <tt>SANITIZE_ADDRESS</tt> Use address sanitizer debugging option.
		* * <tt>SANITIZE_LEAK</tt> Use leak sanitizer debugging option.
		* * <tt>SANITIZE_MEMORY</tt> Use memory sanitizer debugging option.
		* * <tt>SANITIZE_THREAD</tt> Use thread sanitizer debugging option.
		* * <tt>SANITIZE_UNDEFINED</tt> Use undefined sanitizer debugging option.
		* * <tt>SANITIZE_FLOAT-DIVIDE-BY-ZERO</tt> Use float-divide-by-zero sanitizer debugging option.
		* <table>
		* <caption id="build_system_user_cmake_dev_opts">Build options for developers.</caption>
		* <tr><th>Option <th>Discrption
		* <tr><td><tt>USE_PCH</tt> <td>Use precomiled headers during computation. Most users should keep this on.
		* <tr><td><tt>SAVE_KERNEL_SOURCE</tt> <td>Option to dump the generated compute kernel source code to disk.
		* <tr><td><tt>USE_INPUT_CACHE</tt> <td>Option to cache registers for the kernel arguments.
		* <tr><td><tt>USE_CONSTANT_CACHE</tt> <td>Option to use registers to cache constant values otherwise constanst are inlined.
		* <tr><td><tt>SHOW_USE_COUNT</tt> <td>Generates information on the number of times a register is used.
		* <tr><td><tt>USE_INDEX_CACHE</tt> <td>Option to use registers to cache array indicies.
		* <tr><th colspan="2">Sanitizer Flags
		* <tr><td><tt>SANITIZE_ADDRESS</tt> <td>Use address sanitizer debugging option.
		* <tr><td><tt>SANITIZE_LEAK</tt> <td>Use leak sanitizer debugging option.
		* <tr><td><tt>SANITIZE_MEMORY</tt> <td>Use memory sanitizer debugging option.
		* <tr><td><tt>SANITIZE_THREAD</tt> <td>Use thread sanitizer debugging option.
		* <tr><td><tt>SANITIZE_UNDEFINED</tt> <td>Use undefined sanitizer debugging option.
		* <tr><td><tt>SANITIZE_FLOAT-DIVIDE-BY-ZERO</tt><td>Use float-divide-by-zero sanitizer debugging option.
		* </table>
		*/

graph_docs/general.dox

+39 −25

Original line number	Diff line number	Diff line
		@@ -5,29 +5,35 @@
		* @section general_concepts_introduction Introduction
		* This page documents general concepts of the graph_framework.
		*
		* @section general_concepts_definitions Definitions.
		* * <b>node</b> A leaf or branch on the graph tree.
		* * <b>graph</b> A data stucture connecting leaf nodes.
		* * <b>reduce</b> A tranformation of the graph to remove leaf_nodes.
		* * <b>auto differentiation</b> A tranformation of the graph build derivatives.
		* * <b>compiler</b> A tool for translating from one language to another.
		* * <b>JIT</b> Just-in-time compile.
		* * <b>kernel</b> A code function that runs on a batch of data.
		* * <b>pre_item</b> A kernel to run before running the main kernels.
		* * <b>work_iten</b> A instance of kernel.
		* * <b>converge_item</b> A kernel that is run until a convergence test is met.
		* * <b>workflow</b> A series of work items.
		* * <b>backend</b> The device the kernel is run on.
		* * <b>recursion</b> See definition of recursion.
		* * <b>safe math</b> Run time checks to avoid off normal conditions.
		* * <b>API</b> Application programming interface.
		* * <b>Host</b> The place where kernels are launched from.
		* * <b>Device</b> The device side where kernels are run.
		* @section general_concepts_definitions Definitions
		* <table>
		* <caption id="general_concepts_glossery">Glossery of terms</caption>
		* <tr><th>Concept <th>Definition
		* <tr><td><b>node</b> <td>A leaf or branch on the graph tree.
		* <tr><td><b>graph</b> <td>A data stucture connecting leaf nodes.
		* <tr><td><b>reduce</b> <td>A tranformation of the graph to remove leaf_nodes.
		* <tr><td><b>auto differentiation</b><td>A tranformation of the graph build derivatives.
		* <tr><td><b>compiler</b> <td>A tool for translating from one language to another.
		* <tr><td><b>JIT</b> <td>Just-in-time compile.
		* <tr><td><b>kernel</b> <td>A code function that runs on a batch of data.
		* <tr><td><b>pre_item</b> <td>A kernel to run before running the main kernels.
		* <tr><td><b>work_iten</b> <td>A instance of kernel.
		* <tr><td><b>converge_item</b> <td>A kernel that is run until a convergence test is met.
		* <tr><td><b>workflow</b> <td>A series of work items.
		* <tr><td><b>backend</b> <td>The device the kernel is run on.
		* <tr><td><b>recursion</b> <td>See definition of recursion.
		* <tr><td><b>safe math</b> <td>Run time checks to avoid off normal conditions.
		* <tr><td><b>API</b> <td>Application programming interface.
		* <tr><td><b>Host</b> <td>The place where kernels are launched from.
		* <tr><td><b>Device</b> <td>The device side where kernels are run.
		* </table>
		*
		* <hr>
		* @section general_concepts_graph Graph
		* The graph_framework operates by building tree structure of math operations.
		* In tree form it is easy to traverse nodes in the graph. Take the example of
		* equation of a line.
		* For an example of building expression structures see the
		* @ref tutorial_expression "basic expressions tutroial". In tree form it is
		* easy to traverse nodes in the graph. Take the example of equation of a line.
		* @f{equation}{y=mx + b@f}
		* This equation consists of five leaf nodes. The ends of the tree are clasified
		* as either variables @f$x@f$ or constants @f$m,b@f$. These leaf_nodes are
		@@ -45,14 +51,16 @@
		* Evaluation is repeated until every node in the graph is evaluated.
		* @image{} html line_graph_eval_final.png ""
		*
		* <hr>
		* @section general_concepts_diff Auto Differentiation
		* From the previous @ref general_concepts_graph "section", it was shown how
		* graph can be evaluated. This same evaluation can be applied to build
		* graphs of a function derivative. Lets say that we want to take the derivative
		* of @f$\frac{\partial y}{\partial x}@f$. This is achieved by evaluating the
		* until bottom left most leaf_node is reached. Then a new graph is build
		* starting with @f$\frac{\partial m}{\partial x}=0@f$. Applying the first half
		* of the chain rule we build a new graph for @f$0x@f$
		* graphs of a function derivative. For an example of taking derivatives see the
		* @ref tutorial_derivatives "auto differentiation tutroial". Lets say that we
		* want to take the derivative of @f$\frac{\partial y}{\partial x}@f$. This is
		* achieved by evaluating the until bottom left most leaf_node is reached. Then
		* a new graph is build starting with @f$\frac{\partial m}{\partial x}=0@f$.
		* Applying the first half of the chain rule we build a new graph for @f$0x@f$
		* @image{} html line_graph_dydf1.png ""
		* Then we take the derivative of the right operand and apply the second half
		* of the chain rule to build a new graph for @f$0x=0@f$.
		@@ -60,6 +68,7 @@
		* Evaluation is repeated recursively until the full graph has been evaluated.
		* @image{} html line_graph_dydf_final.png ""
		*
		* <hr>
		* @section general_concepts_reduction Reduction
		* The final expression for @f$\frac{\partial y}{\partial x}@f$ contains many
		* unnecessary nodes in the graph. Instead of building full graphs, we can
		@@ -71,8 +80,11 @@
		* @image{} html line_graph_reduce_final.png ""
		* By reducing graphs as they are build, we can eliminate nodes one by one.
		*
		* <hr>
		* @section general_concepts_compile Compile
		* Once graph expressions are build, they can be compiled to a compute kernel.
		* For an example of compiling expression trees into kernels see the
		* @ref tutorial_workflow "workflow tutroial".
		* Using the same recursive evaluation, we can visit each node of a graph and
		* and create a line of kernel source code. There are three important parts for
		* creating kernels, inputs, outputs, and maps. These three concepts define
		@@ -101,10 +113,12 @@
		* @f$y + \frac{\partial f}{\partial x}@f$
		* can be mapped to update @f$y@f$.
		*
		* <hr>
		* @section general_concepts_workflow Workflows
		* Sequences of kernels are evaluated in workflow. A workflow is defined from
		* workitems which wrap a kernel call.
		*
		* <hr>
		* @section general_concepts_safe_math Safe Math
		* There are some conditions where mathematically, a graph should evaluate to
		* normal number. However, when evaluted suing floating point precison, can lead

graph_docs/main.dox

+8 −1

Original line number	Diff line number	Diff line
		@@ -19,21 +19,28 @@
		* * Enable Auto Differentiation.
		* * Enable easy embedding in C, C++, and Fortran codes.
		*
		* <hr>
		* @section tools User guides for tools
		* @subsection rf_ray_tracing RF Ray tracing
		* This section covers user guides to run the RF Ray traceing code. To run this
		* code, a use selects an equilibrium, a wave distribution function, a solver
		* method, intial ray conditions, and a power obsorption model.
		* method, intial ray conditions, and a power obsorption model. To run an
		* example follow the instructions for the @ref xrays_commandline_example.
		*
		* * @ref equilibrum_models
		* * @ref dispersion_function
		* * @ref solvers
		* * @ref absorption_model
		* * @ref xrays_commandline
		* * @ref xrays_output
		*
		* <hr>
		* @section framework_user Framework user guides
		* * @ref build_system "Compiling the framework."
		* * @ref general_concepts "General concepts."
		* * @ref tutorial "Tutorial"
		*
		* <hr>
		* @section framework_developer Framework developer guides
		* * @ref build_system "Build system."
		* * Code structure

graph_docs/tutorial.dox

+4 −0

Original line number	Diff line number	Diff line
		@@ -50,6 +50,7 @@ int main(int argc, const char * argv[]) {
		* <a href="https://www.cppreference.com/w/cpp/concepts.html">Concept</a> for
		* valid types of floating point types allowed by the framework.
		*
		* <hr>
		* @section tutorial_basic Basic Nodes
		* The graph_framework is built around applying the same equations to a large
		* ensemble. Ensembles are defined from variables. All variables need to have
		@@ -98,6 +99,7 @@ void run_tutorial() {
		* impicit constant was defined for <tt>b</tt>. Node in the implicit case, the
		* actual node for <tt>b</tt> is not created until we use it in an expression.
		*
		* <hr>
		* @section tutorial_expression Basic Expressions
		* Finally lets create our equation of a line @f$y=mx+b@f$ and generate the
		* @f$\LaTeX@f$ expression for it.
		@@ -152,6 +154,7 @@ auto dydb = y->df(m*x);
		@endcode
		* The respective results will be @f$x@f$, @f$1@f$, and @f$0@f$ respectively.
		*
		* <hr>
		* @section tutorial_workflow Making workflow.
		* In this section we will build workflow from these nodes we created. For
		* simplicity we will decrease the number of elements in variable so we can set
		@@ -301,6 +304,7 @@ for (size_t i = 0; i < 10; i++) {
		1.0001
		@endcode
		*
		* <hr>
		* @section tutorial_workflow_newton Newtons Method.
		* In this tutorial we are going to show how we can put all these concepts
		* together to impliment a newtons method. Newtons method if defined as

graph_driver/xrays.cpp

+159 −52

File changed.

Preview size limit exceeded, changes collapsed.